stage 1

docs/DEPLOY.md

@@ -0,0 +1,98 @@
+# Deploying on Unraid
+
+The MRP app is a single Docker container that stores everything (SQLite database + uploaded files + backups) under a single `/data` volume.
+
+## 1. Prepare environment
+
+Pick a host directory on your Unraid array (example: `/mnt/user/appdata/mrp-qrcode/`). This will hold the database and uploaded files, and will survive container upgrades.
+
+Generate a strong app secret:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
+```
+
+## 2. docker-compose (recommended)
+
+Create `.env` next to `docker-compose.yml`:
+
+```env
+APP_URL=https://mrp.yourdomain.tld
+APP_SECRET=<paste-the-secret-from-step-1>
+BOOTSTRAP_ADMIN_EMAIL=you@yourdomain.tld
+BOOTSTRAP_ADMIN_PASSWORD=<a-strong-password>
+BOOTSTRAP_ADMIN_NAME=Your Name
+```
+
+Then:
+
+```bash
+docker compose up -d --build
+```
+
+The container will:
+
+1. Create `/data/uploads` and `/data/backups` inside the volume.
+2. Run `prisma migrate deploy`.
+3. Create the bootstrap admin if no admin exists.
+4. Start the web server on port 3000.
+
+## 3. Bind the `/data` volume to host storage (Unraid)
+
+If you prefer a host bind mount over the named volume, replace the `volumes:` block in `docker-compose.yml` with:
+
+```yaml
+    volumes:
+      - /mnt/user/appdata/mrp-qrcode:/data
+```
+
+Make sure the host directory is owned by UID 1001 (the `nextjs` user inside the container):
+
+```bash
+mkdir -p /mnt/user/appdata/mrp-qrcode
+chown -R 1001:1001 /mnt/user/appdata/mrp-qrcode
+```
+
+## 4. Reverse proxy / subdomain
+
+Point your reverse proxy (SWAG, Nginx Proxy Manager, Caddy, Traefik — whatever is already on your Unraid) at `http://<container-ip>:3000` and terminate TLS there.
+
+`APP_URL` must match the externally reachable URL — it is embedded in QR code payloads and used for absolute links. If operators scan a card and land on `http://10.x.x.x:3000`, their phone probably cannot reach that IP; always set `APP_URL` to the public subdomain.
+
+## 5. Backups
+
+The container does not yet run automatic backups. Until step 9 of the build plan ships, back up `/data` with your Unraid backup strategy:
+
+- `/data/app.db` (SQLite file)
+- `/data/app.db-wal` and `/data/app.db-shm` if present (SQLite WAL sidecars)
+- `/data/uploads/`
+
+A safe way to snapshot a live SQLite DB is:
+
+```bash
+docker exec mrp-qrcode sqlite3 /data/app.db ".backup '/data/backups/app-$(date +%F).db'"
+```
+
+## 6. Upgrades
+
+```bash
+git pull
+docker compose up -d --build
+```
+
+Migrations run automatically on start. Before major upgrades, snapshot the DB as above.
+
+## 7. First-login checklist
+
+1. Sign in at `/login/admin` with the bootstrap credentials.
+2. Change your password (admin settings — shipping in a later step).
+3. Create your operators (each gets a name and a 4-digit PIN).
+4. Add your machines.
+5. Create operation templates for repetitive steps.
+6. Create your first project.
+
+## Troubleshooting
+
+- **`APP_SECRET must be at least 32 chars`** — the container refuses to start without one. Regenerate as shown in step 1.
+- **`migrations/` is empty** — run `npx prisma migrate dev --name init` locally once, commit the generated `prisma/migrations/` directory, rebuild the image.
+- **Healthcheck failing** — `docker logs mrp-qrcode` and check DB permissions on `/data`.