Add user/admin/install manuals

2026-04-21 10:29:56 -04:00
parent df7bc9ff71
commit 55e4f18509
4 changed files with 422 additions and 1 deletions
@@ -0,0 +1,128 @@
+# Mastermind MVP — Install Manual
+
+This is the **operator install guide** for a private deployment (LAN/Tailscale or behind your reverse proxy).
+
+## 0) Prerequisites
+- Docker Engine + Docker Compose v2
+- A hostname you can reach (Tailscale IP or reverse-proxy hostname)
+
+Repository layout:
+- `docker-compose.yml`
+- `web/` (Express app)
+- `worker/` (background worker)
+- `data/` (persistent volume directory)
+
+---
+
+## 1) Configure environment
+```bash
+cd /root/clawd/mastermind-mvp
+cp .env.example .env
+```
+
+Edit `.env`:
+- `DB_PASSWORD` — Postgres password (used in compose)
+- `SESSION_SECRET` — **required in production** (>=24 chars). Generate:
+  ```bash
+  openssl rand -base64 48
+  ```
+- `BASE_URL` — the public base URL users will hit
+  - e.g. `http://100.x.y.z:3005` for Tailscale
+  - or `https://mm.yourdomain.com` behind a reverse proxy
+- `TRUST_PROXY=true` if behind a reverse proxy
+- `COOKIE_SECURE=true` if users access via HTTPS
+
+Bootstrap owner (first run only):
+- `BOOTSTRAP_OWNER_EMAIL`
+- `BOOTSTRAP_OWNER_PASSWORD`
+
+Important:
+- Bootstrap is only created if **no local identities exist** in the DB.
+
+---
+
+## 2) Start the stack
+```bash
+docker compose up -d --build
+```
+
+Services:
+- `db` (Postgres)
+- `web` (Express on port 3005)
+- `worker` (stub)
+
+---
+
+## 3) Verify health
+From the host:
+```bash
+curl -fsS http://localhost:3005/health
+```
+Expected:
+```json
+{"ok":true}
+```
+
+Then open:
+- `BASE_URL/login`
+
+---
+
+## 4) First login
+Use the bootstrap credentials you set.
+Then immediately change the password:
+- `/account/password`
+
+---
+
+## 5) Reverse proxy notes (optional)
+If you run behind Traefik/Nginx/Caddy:
+- proxy to `http://127.0.0.1:3005`
+- set `BASE_URL=https://mm.yourdomain.com`
+- set `TRUST_PROXY=true`
+- set `COOKIE_SECURE=true`
+
+---
+
+## 6) Update
+```bash
+cd /root/clawd/mastermind-mvp
+docker compose down
+git pull
+docker compose up -d --build
+```
+
+---
+
+## 7) Backup
+Data lives under `./data/`.
+
+Recommended quick snapshot:
+```bash
+cd /root/clawd/mastermind-mvp
+docker compose down
+
+tar -czf mastermind_backup_$(date +%Y%m%d_%H%M%S).tar.gz data .env docker-compose.yml
+
+docker compose up -d --build
+```
+
+---
+
+## 8) Common troubleshooting
+### Login fails after changing .env bootstrap
+Bootstrap only applies on empty DB. If you already ran it once:
+- reset password via `/admin/users`
+- or wipe `data/postgres` if you truly want a fresh instance
+
+### Cookies / sessions don’t stick
+Usually a BASE_URL / COOKIE_SECURE / TRUST_PROXY mismatch.
+- HTTP access → `COOKIE_SECURE=false`
+- HTTPS access → `COOKIE_SECURE=true` and correct `BASE_URL=https://...`
+
+### Port conflicts
+Compose binds:
+- web: `3005:3005`
+- db: `5433:5432`
+
+Change host ports if needed.