89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# 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`.
|