# 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.