From a40267e490b6f7d6e47c942e8ea1c778855f7923 Mon Sep 17 00:00:00 2001 From: Marcel Date: Mon, 11 May 2026 20:05:14 +0200 Subject: [PATCH] docs(deployment): document IMPORT_HOST_DIR and mass-import workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DEPLOYMENT.md line 81 declares any compose env var missing from §2 a blocking review comment. IMPORT_HOST_DIR (added on this branch) was unmentioned. Adds the row and rewrites §6.4 so the staging/prod operator workflow (rsync host → set env → trigger import) is in the runbook, not just buried in compose comments. Addresses review feedback from Markus and Tobias on #526. Co-Authored-By: Claude Opus 4.7 --- docs/DEPLOYMENT.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index bd7b7a1a..a2dc55ca 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -97,6 +97,7 @@ All vars are set in `.env` at the repo root (copy from `.env.example`). The back | `APP_BASE_URL` | Public-facing URL for email links | `http://localhost:3000` | YES (prod) | — | | `APP_OCR_BASE_URL` | Internal URL of the OCR service | — | YES | — | | `APP_OCR_TRAINING_TOKEN` | Secret token for OCR training endpoints | — | YES (prod) | YES | +| `IMPORT_HOST_DIR` | Absolute host path holding the ODS spreadsheet + PDFs for the `/admin/system` mass-import card. Mounted read-only at `/import` inside the backend (compose-only — backend reads via `app.import.dir`). Compose refuses to start when unset, so staging and prod cannot accidentally share the source. Convention: `/srv/familienarchiv-staging/import` and `/srv/familienarchiv-production/import` | — | YES (prod compose) | — | | `MAIL_HOST` | SMTP host | `mailpit` (dev) | YES (prod) | — | | `MAIL_PORT` | SMTP port | `1025` (dev) | YES (prod) | — | | `MAIL_USERNAME` | SMTP username | — | YES (prod) | YES | @@ -329,9 +330,18 @@ bash scripts/download-kraken-models.sh ### Trigger a mass import (Excel/ODS) -1. Place the import file in the `import/` bind mount on the backend container. -2. Call `POST /api/admin/trigger-import` (requires `ADMIN` permission). -3. The import runs asynchronously — poll `GET /api/admin/import-status` or watch backend logs. +**Dev:** drop the ODS spreadsheet + PDFs into `./import/` at the repo root — the dev compose bind-mounts it to `/import` automatically. + +**Staging/production:** + +1. Pre-stage the payload on the host. Convention: `/srv/familienarchiv-staging/import/` or `/srv/familienarchiv-production/import/`. + ```bash + rsync -avh --progress ./import/ user@host:/srv/familienarchiv-staging/import/ + ``` +2. Make sure `IMPORT_HOST_DIR=` is set in `.env.staging` / `.env.production` (the nightly/release workflows already write this — see §3). Compose refuses to start without it. +3. Redeploy the stack so the bind mount picks up — or, if the mount is already in place, skip to step 4. +4. Call `POST /api/admin/trigger-import` (requires `ADMIN` permission), or click the "Import starten" button on `/admin/system`. +5. The import runs asynchronously — poll `GET /api/admin/import-status`, watch `/admin/system`, or tail the backend logs. ---