# 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 on port
`3000`, with a persistent named volume (`flashcard-data`) for the SQLite database.
Migrations run automatically on every container start.

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

```bash
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.

```bash
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>:3000`
  (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>:3000`.

## 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

```bash
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`.