threadcount-community/docs/self-hosting.md

Self-hosting ThreadCount

ThreadCount is free software a facility runs on its own server. There is nothing to buy and no account with anyone: you take the source, build it, and run it where your own data can live. This page says how to run it, how to keep it, and what it needs from you.

What you are running

One instance serves one facility, with the coordinator app at /app, the phone counter at /m and the staff app at /my, in full. There is no limit on staff records, garments or issues, and no state in which the product stops accepting changes. Users sign in with a password, and with a code from an authenticator app where they have turned two-factor on. / goes to the sign-in page.

Nothing leaves your server unless you configure it. Error reports go nowhere until you set NEXT_PUBLIC_GLITCHTIP_DSN to a collector of your own, and usage statistics go nowhere until you set the Umami variables to a tracker of your own. Transactional email is your SMTP server, or none. Cloudflare Turnstile on sign-in and sign-up is optional: set both keys to enforce it, and without it the per-address rate limits stand alone.

Your instance is yours, and so is the privacy statement your staff read. The product's screens link to terms and a privacy notice from a few places (the staff sign-in, account screens); set NEXT_PUBLIC_TERMS_URL and NEXT_PUBLIC_PRIVACY_URL to your own documents before you build. With neither set, no link shows.

Running it

docker-compose.yml runs three services: db (Postgres 16, in a named volume), migrate (a one-shot prisma migrate deploy that runs before the app on every up), and app (Next.js's standalone server, port 3000, photographs in a second named volume). Put TLS in front of port 3000. A minimal Caddyfile:

uniforms.example.health {
    reverse_proxy 127.0.0.1:3000
}

The image is built on your machine, not pulled, because NEXT_PUBLIC_SITE_URL and the optional Turnstile site key are compiled into the browser bundle. If you change either, rebuild: docker compose up -d --build.

The first facility

Open the hostname. Create an account; that creates a facility and makes you its administrator. Under Settings, name your staff groups first (nothing works until a facility has them), then load the catalogue, departments, staff register, barcodes and opening stock from CSV under Settings › Data. Add a second administrator under Settings › Account › Users before you sign out — a forgotten password with one admin and no SMTP locks the facility.

Then set SIGNUPS_DISABLED=1 in .env and docker compose up -d. Your instance is now one facility, and nobody else can create another.

Upgrading

Each release replaces the repository's history rather than adding to it, so a plain git pull refuses to merge. Fetch and move to the release instead. Your .env is not tracked and stays put.

git fetch origin
git reset --hard origin/main
docker compose up -d --build

migrate applies any new schema migrations before the new app starts; the old app keeps serving until then. Take a backup first (below). Releases that need more than that say so in their notes.

Backups

docker/backup.sh <directory> writes one directory per run: the database as a custom-format pg_dump and the photographs as a tarball, keeping the last fourteen. Run it nightly from cron:

30 3 * * * cd /srv/threadcount && docker/backup.sh /srv/backups/threadcount >> /var/log/threadcount-backup.log 2>&1

Copy that directory somewhere off the machine. A backup on the same disk as the database is not a backup.

Separately, an administrator can download the whole facility as one JSON file from Settings › Data at any time, and restore it into a fresh instance from the same screen. That file is the portable form; the pg_dump is the fast one.

Restoring

docker compose down
docker volume rm threadcount_db threadcount_photos     # only if you mean to replace everything
docker compose up -d db
docker compose exec -T db pg_restore -U threadcount -d threadcount --clean --if-exists < 2026-09-13-033001/threadcount.dump
docker compose up -d
docker compose cp 2026-09-13-033001/photos app:/data/   # after extracting photos.tgz

The Android apps

The two Android apps (ThreadCount, the counter; ThreadCount Staff) have no server of their own, so each phone is told which one to use. On the app's first screen tap the "Server" line and enter your hostname. The app checks it over HTTPS (it calls /api/app-info, which every ThreadCount server answers), saves it on the phone, and opens your counter or staff screens from then on. The choice is per phone; "Change" is always on the first screen, and the sign-in screens show which server they are talking to.

Emailed approval links do not open straight in the staff app. They open in the phone's browser instead, and work there. The phone must be able to reach your server over HTTPS with a certificate it trusts; a self-signed certificate is refused.

Without the apps, the same screens work in a phone's browser: https://your-host/m for the counter (camera scanning works in Chrome and Edge) and https://your-host/my for staff.

Environment reference

.env.example lists every variable the application reads, with a comment on each. The ones that matter for a Community instance are SESSION_SECRET, POSTGRES_PASSWORD, NEXT_PUBLIC_SITE_URL, EDITION, NEXT_PUBLIC_TERMS_URL, NEXT_PUBLIC_PRIVACY_URL, the SMTP_* group, and SIGNUPS_DISABLED. Leave the Turnstile and GlitchTip variables empty unless you run those yourself.

Getting help

Questions and problems go to the issue tracker: github.com/pricehq/threadcount-community/issues.