Add user/admin/install manuals
This commit is contained in:
+145
@@ -0,0 +1,145 @@
|
||||
# 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).
|
||||
@@ -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.
|
||||
@@ -56,7 +56,12 @@ A portable, self-hosted dashboard that supports an Assistant PM workflow (starti
|
||||
- `/admin/email-rules`
|
||||
|
||||
## Quick start
|
||||
See **INSTALL.md**.
|
||||
See **INSTALL.md** (quick) or **INSTALL_MANUAL.md** (detailed).
|
||||
|
||||
## Manuals
|
||||
- **USER_MANUAL.md** — day-to-day usage
|
||||
- **ADMIN_MANUAL.md** — admin/owner operations
|
||||
- **INSTALL_MANUAL.md** — install + deploy + backup
|
||||
|
||||
Common local commands:
|
||||
- `npm test` — run the repo test suite
|
||||
|
||||
+143
@@ -0,0 +1,143 @@
|
||||
# Mastermind MVP — User Manual
|
||||
|
||||
This manual is for day‑to‑day users of the Mastermind MVP dashboard.
|
||||
|
||||
## What Mastermind is
|
||||
Mastermind is a self‑hosted Assistant Project Manager (APM) dashboard that helps you:
|
||||
- create and manage projects
|
||||
- import emails into an **Inbox**
|
||||
- automatically sort/assign emails using rules
|
||||
- create **draft‑first** documents (PCO and RFI) from emails
|
||||
- keep an **audit trail** of key actions
|
||||
|
||||
It is designed to be private (LAN/Tailscale) and safe by default (no auto‑sending).
|
||||
|
||||
---
|
||||
|
||||
## Login / Logout
|
||||
### Login
|
||||
1. Open the login page:
|
||||
- `https://<your-host>/login`
|
||||
2. Sign in with your **local email + password**.
|
||||
|
||||
If Google/Microsoft OAuth is enabled by the admin, you may also see those buttons.
|
||||
|
||||
### Logout
|
||||
- Click **Logout** in the UI (or go to `/logout`).
|
||||
|
||||
---
|
||||
|
||||
## Home
|
||||
After logging in, you land on **Home** (`/`). From here you can reach:
|
||||
- Projects
|
||||
- Inbox
|
||||
- Drafts
|
||||
- Docs
|
||||
|
||||
---
|
||||
|
||||
## Projects
|
||||
### View projects
|
||||
- Go to `/projects`
|
||||
- You’ll see projects you’re a member of.
|
||||
|
||||
### Create a project
|
||||
1. Go to `/projects`
|
||||
2. Fill the **Create Project** form (name is required)
|
||||
3. Submit
|
||||
|
||||
Fields you may use:
|
||||
- **Name** (required)
|
||||
- **Job #** (optional)
|
||||
- **Role mode** (defaults to EC)
|
||||
- **GC name** (optional)
|
||||
- **City/State** (optional)
|
||||
- **Keywords** (important for auto-sorting)
|
||||
|
||||
### Edit a project
|
||||
- Open the project: `/projects/<id>`
|
||||
- Update fields and save
|
||||
|
||||
### Project inbox
|
||||
- From the project page, use **Project Inbox** to view emails already assigned to that project.
|
||||
|
||||
---
|
||||
|
||||
## Inbox (manual import)
|
||||
Mastermind currently supports manual email import via `.eml` upload.
|
||||
|
||||
### Upload email(s)
|
||||
1. Go to `/inbox`
|
||||
2. Use **Upload .eml**
|
||||
3. Select one or more `.eml` files
|
||||
4. Submit
|
||||
|
||||
Notes:
|
||||
- The system stores the raw `.eml` and any attachments.
|
||||
- Uploaded emails initially appear as **Unsorted**.
|
||||
|
||||
### Assign an email to a project
|
||||
1. Open an email from `/inbox`
|
||||
2. Choose a project in the **Assign** dropdown
|
||||
3. Submit
|
||||
|
||||
### View email details + attachments
|
||||
- Open `/inbox/<emailId>`
|
||||
- Attachments can be downloaded from the email page.
|
||||
|
||||
---
|
||||
|
||||
## Drafts (PCO / RFI)
|
||||
Drafts are **generated from an email** and then edited by you.
|
||||
|
||||
### Create a PCO draft from an email
|
||||
1. Open an email (`/inbox/<id>`)
|
||||
2. Click **Create PCO Draft**
|
||||
3. You’ll be taken to the draft editor
|
||||
|
||||
### Create an RFI draft from an email
|
||||
Same flow, using **Create RFI Draft**.
|
||||
|
||||
### Edit + save a draft
|
||||
- Draft editor pages:
|
||||
- `/drafts/pco/<id>`
|
||||
- `/drafts/rfi/<id>`
|
||||
- Edit the title/body
|
||||
- Click **Save**
|
||||
|
||||
### Export a draft
|
||||
- Use the export links:
|
||||
- PCO: `/drafts/pco/<id>/export.md`
|
||||
- RFI: `/drafts/rfi/<id>/export.md`
|
||||
|
||||
---
|
||||
|
||||
## Tips for better sorting
|
||||
- Put meaningful **keywords** in each Project.
|
||||
- Ask an admin to create rules (sender domain, subject contains job #, etc.).
|
||||
- Start simple: one rule per project is often enough.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
### “Login failed”
|
||||
- Confirm email and password.
|
||||
- If you recently changed password, log out and back in.
|
||||
- Ask an admin to reset your password.
|
||||
|
||||
### Upload fails
|
||||
- Confirm files are `.eml`.
|
||||
- Try fewer files at once.
|
||||
- If it consistently fails, ask admin to check disk space.
|
||||
|
||||
### I can’t see a project
|
||||
- You must be added as a project member (admin/owner action).
|
||||
|
||||
---
|
||||
|
||||
## Glossary
|
||||
- **Inbox**: Imported emails awaiting sorting/assignment.
|
||||
- **PCO**: Potential Change Order draft.
|
||||
- **RFI**: Request For Information draft.
|
||||
- **Rule**: An automatic matching condition that assigns an email to a project.
|
||||
- **Audit log**: A record of important actions (imports, assignments, admin changes).
|
||||
Reference in New Issue
Block a user