Self-host

Run Bitfield on your own machine or server. Same app as cloud; uploads stay on disk when no Blob token is set.

Requirements

Node.js 22+
pnpm
Docker (Postgres 16)

Quick start

The repo-root runner starts Postgres, migrates, and launches Next in the background:

pnpm install          # first time only
./bitfield start      # or: ./bitfield start dev
./bitfield status
# …work…
./bitfield stop

start copies .env.example to .env if needed. App logs go to .bitfield/app.log.
./bitfield start prod builds first, then runs pnpm start.

Manual equivalent

pnpm install
cp .env.example .env
docker compose up -d --wait
pnpm db:migrate
pnpm dev

Open http://localhost:3000. Create the first admin with the bootstrap env in .env, then:

pnpm db:bootstrap

That account is role=admin. Sign in with that email/password (OAuth is optional locally).

Uploads

Leave BLOB_READ_WRITE_TOKEN unset. Images land in ./data/uploads (gitignored). The same binary uses Vercel Blob when that token is present — see Cloud deploy.

LAN and iPad

http://192.168.x.x:3000 works for browsing: Next and Better Auth pick up this machine’s LAN IPs at process start. Restart after a DHCP / Wi-Fi change. Prefer localhost when you can (Secure Context).

Password auth on LAN needs no extra env. OAuth on LAN needs BETTER_AUTH_URL=http://<lan-ip>:3000 to match the IdP callback URLs.

Installing as a PWA (Add to Home Screen) needs HTTPS or localhost. A plain LAN http:// URL will not install. The service worker is off in pnpm dev; use pnpm build && pnpm start to exercise it.

Locking signup

Set AUTH_DISABLE_SIGNUP=true after you have an admin, then restart. New people join via Settings → User Management → invite link. Details: Accounts & invites.

Compose credentials in .env.example are for local use only. Point DATABASE_URL at your own Postgres if you are not using the bundled Compose file.