kooltab-backoffice/docs/production.md

Production on Coolify

KoolTap is deployed with Coolify's Docker Compose build pack, from docker-compose.coolify.yml.

Once

1. Create a PostgreSQL database resource in Coolify and turn on its scheduled backups.

2. Create a Docker Compose resource from this repository with docker-compose.coolify.yml.

3. Give the services their domains, on one site so the session cookie reaches the API:

   • api → https://api.example.com:3001
   • dashboard → https://example.com:3000

4. Set the environment variables:

   Variable
   DATABASE_URL	The database resource's internal connection URL
   API_URL	https://api.example.com (baked into the dashboard at build time)
   DASHBOARD_URL	https://example.com (CORS and links)
   RESEND_API_KEY, RESEND_FROM_EMAIL	Email; without a key nothing is sent
   TRUST_PROXY	1 behind Coolify's proxy, 2 with Cloudflare proxying too
   MIN_APP_VERSION	Optional: make older terminal apps update

   JWT_SECRET is generated by Coolify (SERVICE_BASE64_64_JWT).

5. Deploy. The API applies the database migrations before it starts.

6. Create the first venue and its admin, in the API container's terminal:

   node dist/cli/setup.js "My Venue" admin@myvenue.com '<a strong password>'
   

   It does nothing when there is a venue already. Superadmins belong to no venue: node dist/cli/superadmin.js <email> --create "<name>" <password> adds one, superadmin.js <email> promotes a user, and --revoke <venue id> makes a superadmin an admin of that venue.

Switching over from 1.x

2.0 starts with an empty database: nothing comes over from the 1.x backoffice.

1. Before switching, let every tablet sync and settle (or write down) the open tabs. Export what you want to keep.
2. Deploy 2.0 on a new, empty database and set up the venues, users and products.
3. A 1.x tablet that syncs with it gets 426 and shows "update the app"; its unsent sales stay on the tablet.
4. Update the app on each tablet to 2.0. It keeps its settings (PIN, theme, language, rows) and starts unpaired, with empty tabs and history: pair it with a code from Settings and it loads the venue's catalog and open tabs.

Backups

Back up the database (Coolify does this) and the images volume, which holds the product pictures.

Every deploy

Push; Coolify builds both images and restarts. Migrations run on start. If one fails the API doesn't start and the superadmin page's System tab lists it; fix it and redeploy.

Health

GET /api/v1/health answers 503 when the database is unreachable; the compose file uses it as the healthcheck.