Installation

Geekonomics is a self-hosted application that runs as a Docker container. This guide covers the one-time setup on a new server.

Requirements

Component	Minimum
OS	Any Linux (Ubuntu, Debian, Unraid, etc.)
RAM	512 MB
Disk	1 GB + space for uploads/backups
Docker	20.x or later
Docker Compose	v2 (included with Docker Desktop, docker compose plugin)

No database server required — Geekonomics uses SQLite.

1. Clone the repository

SSH into your server and clone to your preferred location:

cd /mnt/user/appdata        # Unraid example
git clone https://github.com/oneofthegeeks/geekonomics-app.git
cd geekonomics-app

2. Configure environment variables

cp .env.example .env
nano .env

At minimum, set these two values:

SESSION_SECRET=generate-a-long-random-string-here
ENCRYPTION_KEY=generate-64-hex-chars-here

Generate them:

# SESSION_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# ENCRYPTION_KEY (must be exactly 64 hex chars)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

See Configuration for all environment variable options.

3. Start the container

docker compose up -d --build

The first build takes 2–3 minutes (Vite frontend build is the slow part). After that, the app is running on port 3001.

docker compose logs -f    # watch logs
docker compose ps         # check status

4. Access the setup wizard

Open http://your-server-ip:3001 in a browser. On first launch you'll be redirected to /setup. Complete the 3-step wizard:

1. Create your admin account — name, email, password
2. Company profile — name, address, invoice prefix, tax rate
3. Business lines — at least one (e.g. "Consulting", "Products")

Once complete, you're logged in and ready to start entering transactions.

5. Set up external HTTPS access (optional but recommended)

For remote access, use a Cloudflare tunnel:

# Install cloudflared on your server
cloudflared tunnel login
cloudflared tunnel create geekonomics

# Copy the credentials JSON into the repo
cp ~/.cloudflared/<tunnel-id>.json cloudflared/

# Edit cloudflared/config.yml with your tunnel ID and hostname
# Then add the CNAME in Cloudflare DNS

See Deployment for the full Cloudflare + Unraid setup.

Directory structure after install

geekonomics-app/
├── data/           → SQLite DB + session store (bind-mounted, never deleted on rebuild)
├── uploads/        → Receipt file attachments (bind-mounted)
├── cloudflared/    → Tunnel credentials (gitignored)
├── .env            → Your environment variables (gitignored)
└── docker-compose.yml

Data persistence

The data/ and uploads/ directories are bind-mounted into the container. Rebuilding or restarting the container does not affect your data.