145 lines
3.7 KiB
Markdown
145 lines
3.7 KiB
Markdown
# Mastermind MVP — Admin Manual
|
||
|
||
This manual is for the **owner/admin** who runs Mastermind.
|
||
|
||
## Admin areas
|
||
- Users: `/admin/users`
|
||
- Audit log: `/admin/audit`
|
||
- Email connectors: `/admin/email`
|
||
- Email rules: `/admin/email-rules`
|
||
|
||
---
|
||
|
||
## 1) User management
|
||
Path: `/admin/users`
|
||
|
||
### Create a user
|
||
- Provide:
|
||
- email
|
||
- display name (optional)
|
||
- role (owner/apm)
|
||
- temporary password
|
||
|
||
Password rules (enforced):
|
||
- at least **12 characters**
|
||
- includes uppercase + lowercase + number
|
||
|
||
### Reset a password
|
||
- Use **Reset** on the user row.
|
||
|
||
### Disable / enable a user
|
||
- Use **Toggle**.
|
||
|
||
### Delete a user
|
||
- Use **Delete** (removes the user and their identities).
|
||
|
||
**Important security note:**
|
||
- Today, the database default for `users.role` is `owner`. If you enable Google/Microsoft OAuth, new OAuth sign-ins may end up as owners unless the code is adjusted. Treat OAuth enablement as a privileged action.
|
||
|
||
---
|
||
|
||
## 2) Audit log
|
||
Path: `/admin/audit`
|
||
|
||
The audit log captures:
|
||
- login successes/failures
|
||
- admin actions (user creation, reset, disable)
|
||
- project creation/updates
|
||
- inbox imports, assignments, auto-assignments
|
||
|
||
Use this to answer: “who did what, when.”
|
||
|
||
---
|
||
|
||
## 3) Email connectors (status + enable/disable)
|
||
Path: `/admin/email`
|
||
|
||
Connectors exist for:
|
||
- Gmail
|
||
- Microsoft
|
||
|
||
In the MVP, these are **status toggles/placeholders** until OAuth ingestion is implemented end-to-end.
|
||
|
||
### Configured vs Authorized
|
||
- **Configured** means OAuth client ID/secret exists in environment variables.
|
||
- **Authorized** will remain false until an OAuth flow stores tokens and the worker sync is implemented.
|
||
|
||
---
|
||
|
||
## 4) Email rules (auto-assign)
|
||
Path: `/admin/email-rules`
|
||
|
||
Rules are evaluated in priority order:
|
||
- lower `priority` number runs first
|
||
|
||
Match types:
|
||
- `from_domain` — match sender domain
|
||
- `from_contains` — match substring in From
|
||
- `subject_contains` — match substring in Subject
|
||
- `body_contains` — match substring in Body
|
||
- `thread_key` — exact match thread key
|
||
|
||
### Recommended rule patterns
|
||
- Create one `from_domain` rule per key vendor/GC domain.
|
||
- Add a `subject_contains` rule for job numbers.
|
||
- Keep priority tight:
|
||
- job-number rules (priority 40)
|
||
- domain rules (priority 50)
|
||
- general keywords last (priority 100+)
|
||
|
||
---
|
||
|
||
## 5) Storage + backups
|
||
Mastermind stores data under `./data/`:
|
||
- `data/postgres/` — Postgres database
|
||
- `data/uploads/` — raw `.eml` uploads
|
||
- `data/attachments/` — extracted email attachments
|
||
|
||
### Backup (manual)
|
||
```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
|
||
```
|
||
|
||
### Restore
|
||
```bash
|
||
cd /root/clawd/mastermind-mvp
|
||
docker compose down
|
||
rm -rf data
|
||
|
||
tar -xzf mastermind_backup_YYYYMMDD_HHMMSS.tar.gz
|
||
|
||
docker compose up -d --build
|
||
```
|
||
|
||
---
|
||
|
||
## 6) Operational troubleshooting
|
||
### Web is up but login fails
|
||
- Check if the DB already contains identities; bootstrap only triggers when **no local identities exist**.
|
||
- Reset the password via `/admin/users`.
|
||
|
||
### Disk growth / uploads
|
||
- Inbox uploads and attachments will grow over time.
|
||
- If disk is tight, archive older projects or introduce retention.
|
||
|
||
### Reverse proxy / cookies
|
||
If serving behind HTTPS reverse proxy:
|
||
- set `BASE_URL=https://...`
|
||
- set `TRUST_PROXY=true`
|
||
- set `COOKIE_SECURE=true`
|
||
|
||
Otherwise you’ll see session/cookie weirdness.
|
||
|
||
---
|
||
|
||
## 7) Security checklist (minimum)
|
||
- Change bootstrap owner password immediately after first login.
|
||
- Use a long random `SESSION_SECRET`.
|
||
- Keep the app private to LAN/Tailscale until hardened.
|
||
- Consider enabling CSRF checks for production.
|
||
- Avoid enabling OAuth until role-default behavior is fixed (or restrict by allowlist). |