Mastermind/INSTALL_MANUAL.md

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

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:

  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

docker compose up -d --build

Services:

• db (Postgres)
• web (Express on port 3005)
• worker (stub)

---

3) Verify health

From the host:

curl -fsS http://localhost:3005/health

Expected:

{"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

cd /root/clawd/mastermind-mvp
docker compose down
git pull
docker compose up -d --build

---

7) Backup

Data lives under ./data/.

Recommended quick snapshot:

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.