flashcards/DEPLOY.md

Deploy to Dockge (fastest path: build on the host)

This is the quickest way to get Flashcard running on your Proxmox + Dockge setup. Source comes from Gitea; Dockge builds the image locally and runs it. No container registry, no Gitea Actions, no docker login required.

Repo: https://gitea.hausmans.cloud/bert.hausmans/flashcards

What gets deployed

One container (flashcard) serving the API and the built frontend. It listens on port 3000 inside the container, mapped to 4000 on the Dockge host (4000:3000 in compose.yaml). A persistent named volume (flashcard-data) holds the SQLite database. Migrations run automatically on every container start.

Step 1 — push the code to Gitea (from your dev machine)

cd /Users/berthausmans/Documents/Development/flashcard
git remote add origin https://gitea.hausmans.cloud/bert.hausmans/flashcards.git   # first time only
git push -u origin master

Step 2 — put the stack on the Dockge host

SSH into the host running Dockge. Dockge keeps stacks in /opt/stacks by default.

cd /opt/stacks
git clone https://gitea.hausmans.cloud/bert.hausmans/flashcards.git flashcard

A "flashcard" stack now appears in the Dockge UI (it reads compose.yaml).

Step 3 — configure environment in Dockge

Open the flashcard stack in Dockge and edit the environment: block:

• APP_URL → how you reach the app, e.g. http://<dockge-host-ip>:4000 (this is what verification/reset/invite e-mail links use — get it right).
• COOKIE_SECURE → leave "false" for now (plain HTTP). Flip to "true" only after you put the app behind HTTPS.
• SMTP (Amazon SES) → fill in SMTP_HOST (e.g. email-smtp.eu-west-1.amazonaws.com), SMTP_USER, SMTP_PASS, and SMTP_FROM. Optional for first boot — see Step 5.

Step 4 — deploy

Click Deploy (Dockge runs docker compose up -d --build). First build takes a few minutes (installs deps, builds the frontend, compiles better-sqlite3). When it's up, open http://<dockge-host-ip>:4000.

Step 5 — create the first account (becomes sysadmin)

Go to /register and sign up. The first registered user is automatically the sysadmin.

• If SES is configured: click the verification link in your inbox.
• If you left SMTP empty: grab the verification link from the container logs — in Dockge open the flashcard stack → Logs, and copy the …/verify-email?token=… URL printed by the stub mailer.

Then log in. Done.

Updating later

cd /opt/stacks/flashcard
git pull

Then in Dockge click Deploy again (rebuilds + restarts). The flashcard-data volume — and therefore all lessons, cards and accounts — persists across redeploys.

Notes & gotchas

• Data safety: everything lives in the flashcard-data Docker volume. Don't delete it. Back it up by copying /data/flashcard.db out of the container/volume.
• Secure cookies need HTTPS. With COOKIE_SECURE=true over plain HTTP the browser silently discards the login cookie. Keep it false until you have TLS.
• Mailpit (docker-compose.yml) is dev-only and is ignored here — Dockge uses compose.yaml.
• The backend runs via tsx (TypeScript runtime), matching dev. Migrations are applied automatically by docker-entrypoint.sh before the server starts.

Next step (optional, when you have time)

Move to the Gitea container registry + Gitea Actions so Dockge pulls a pre-built image instead of building on the host. Ask and I'll add a .gitea/workflows/build.yml plus a registry-based compose.yaml.