# Deploy to Dockge via the Gitea container registry

Flashcard ships as one container (API + built frontend). You build the image once,
push it to your Gitea registry, and Dockge pulls it — same pattern as your
`questionnaire` stack.

- Gitea repo: `https://gitea.hausmans.cloud/bert.hausmans/flashcards`
- Registry image: `10.0.10.205:3000/bert.hausmans/flashcards:latest`

## One-time prerequisites (on this Mac)

The registry is plain HTTP on an IP, so Docker must trust it. In **Docker Desktop →
Settings → Docker Engine**, add `10.0.10.205:3000` to `insecure-registries`:

```json
{
  "insecure-registries": ["10.0.10.205:3000"]
}
```

Apply & restart Docker. Then log in to the registry (use your Gitea username and a
Gitea access token or password — run it yourself so the prompt works):

```
! docker login 10.0.10.205:3000
```

(The Dockge host already trusts this registry since `questionnaire` pulls from it.)

## Step 1 — build for amd64 and push

Your Mac is arm64 but the Proxmox host is amd64, so build with `--platform
linux/amd64`. From the repo root:

```bash
docker buildx build --platform linux/amd64 \
  -t 10.0.10.205:3000/bert.hausmans/flashcards:latest \
  --push .
```

That builds the image and pushes it straight to the Gitea registry.

## Step 2 — create the Dockge stack

In Dockge, **+ Compose** → name it `flashcard`, and paste the contents of
`compose.yaml` from this repo (or copy the file into the stack directory). Then edit
the `environment:` block:

- `APP_URL` → how users reach the app, e.g. `http://10.0.10.205:4100`
  (used in verification / reset / invite e-mail links — get it right).
- `COOKIE_SECURE` → leave `false` over plain HTTP; set `true` only behind HTTPS.
- SMTP (Amazon SES) → fill in `SMTP_HOST` / `SMTP_USER` / `SMTP_PASS` / `SMTP_FROM`,
  **or** leave `SMTP_HOST` empty for the first boot (see Step 4).

The stack maps host **4100 → container 4000** and persists the SQLite DB in the
`flashcard-data` volume.

## Step 3 — deploy

Click **Deploy**. Dockge pulls the image and starts it. Open
`http://10.0.10.205:4100`. Migrations run automatically on container start.

## Step 4 — create the first account (becomes sysadmin)

Go to `/register` and sign up — the **first registered user is automatically the
sysadmin**.

- SES configured → click the verification link in your inbox.
- SMTP left empty → open the stack's **Logs** in Dockge and copy the
  `…/verify-email?token=…` link printed by the stub mailer.

Then log in. Done.

## Updating later

Rebuild & push the new image, then redeploy in Dockge:

```bash
docker buildx build --platform linux/amd64 \
  -t 10.0.10.205:3000/bert.hausmans/flashcards:latest --push .
```

In Dockge: open the **flashcard** stack → **Pull** (fetches the new image) →
**Deploy**. The `flashcard-data` volume — and all lessons, cards and accounts —
survives redeploys.

> Tip: for safe rollbacks, also tag a version alongside `latest`, e.g.
> `-t 10.0.10.205:3000/bert.hausmans/flashcards:2026-05-21 -t 10.0.10.205:3000/bert.hausmans/flashcards:latest`.

## Notes & gotchas

- **Data lives in the `flashcard-data` volume** — don't delete it; back up
  `/app/data/flashcard.db`.
- **Secure cookies need HTTPS.** Over plain HTTP keep `COOKIE_SECURE=false`,
  otherwise the browser drops the login cookie and sign-in silently fails.
- **Mailpit** (`docker-compose.yml`) is dev-only and unrelated to this deploy.
- The backend runs via `tsx` and applies migrations on boot
  (`docker-entrypoint.sh`).

## Optional: automate with Gitea Actions

If you later register a Gitea `act_runner`, I can add a `.gitea/workflows/build.yml`
that builds and pushes on every push to `master`, so you skip the manual buildx step.