129 lines
2.6 KiB
Markdown
129 lines
2.6 KiB
Markdown
# 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.
|