mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-20 20:07:59 +00:00
* Add CLI scaffold and config generators * Add PR stacking note to README * refactor: write embargo init command myself for clarity * refactor: rename Myst and narrow CLI setup flow * Update Phase 1 plans with finalized design decisions Major updates: - Add authentication model (Forgejo sessions for identity, PAT for data access) - Add link types (private email-verified, public time-expired) - Add link creation rules (owner-only) - Add Docker/deployment guidance (Dockerfile only, Dokploy handles orchestration) - Add database model (separate DBs on same PostgreSQL instance) - Add viewer baseline and user dashboard sections - Add SMTP configuration via post-login setup page Key architectural decisions: - Users log in via Forgejo session, no separate Myst login - Service account PAT used for API calls, not user identity - Private links require email verification code - Public links are time-expired for job applications - Myst provides Dockerfile, operators use Dokploy for deployment * Complete CLI init skeleton with CodeRabbit review fixes CLI changes: - Narrow init to Myst-only config generation (no Forgejo provisioning) - Add yoctocolors styling to CLI output - Simplify URL validation logic (remove dead code) - Fix typo in env.ts comment - Remove docker-compose generator (out of scope) - Move example config from src/ to packages/cli/examples/ - Fix CommandName type to match implemented commands only Config changes: - Remove databaseUrl from myst.config.json (DB is .env-only) - Update example config with current fields - Reject non-HTTP schemes before auto-prepending https:// - Use localhost -> 127.0.0.1 in Caddy/Nginx examples - Add file existence checks and 0o600 permissions Build passes after all changes. * docs: rewrite README with Myst branding and architecture - Add Mermaid architecture diagram - Document two link types (private/public) - Explain authentication model - Provide setup steps - Add example configuration - Include Phase 1 completion checklist * fix: correct Mermaid diagram syntax * refactor: streamline README per create-readme skill guidelines - Use blockquote for tagline - Simplify architecture diagram labels - Remove redundant sections (Setup, Example Config, License) - Keep checklist as primary tracking mechanism - Use tables for features and auth - Reduce verbosity throughout * cli: add preflight check and version flag - Add preflightWriteTargets to check file existence before writing - Remove stub commands (start, stop, status) from help text - Add --version flag support - Sequential file writes with preflight check * cleanup: remove empty command stubs and test config - Remove start.ts, stop.ts, status.ts (not implemented yet) - Remove myst.config.json (generated during testing) * cleanup: remove app-ini generator (Forgejo provisioning out of scope) * cleanup: remove empty unused utility files (docker.ts, flags.ts, init.ts) * cleanup: remove examples.ts (examples belong in docs, not deployed code)
3.6 KiB
3.6 KiB
Myst
My stuff, kept private.
Myst is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for code snapshots.
Architecture
flowchart TB
subgraph VPS["VPS / Self-Hosted"]
subgraph Docker["Docker Network"]
Forgejo["Forgejo (Git Server)"]
Postgres["PostgreSQL (2 Databases)"]
Myst["Myst (This Service)"]
Traefik["Traefik (Reverse Proxy)"]
end
Tailscale["Tailscale (Admin Access)"]
end
subgraph External["External"]
Owner["Repo Owner"]
Viewer["Link Recipient"]
end
Owner -->|"Login via Forgejo Session"| Myst
Owner -->|"Create View Link (PAT)"| Forgejo
Myst -->|"Read-only API (PAT)"| Forgejo
Myst -->|"Store Grants"| Postgres
Forgejo -->|"Sessions"| Postgres
Myst -->|"Public Viewer"| Viewer
Myst -->|"Admin UI (Protected)"| Owner
Tailscale -->|"Private Admin Access"| Myst
Traefik -->|"Route HTTPS Traffic"| Myst
Features
Two Link Types
| Type | Verification | Use Case |
|---|---|---|
| Private | Email verification code required | Share with specific individuals |
| Public | No verification, time-expired | Job applications, portfolios |
Security
- Links pinned to immutable
commit_sha— not moving branches - Email verification prevents unauthorized access
- Time-expiration and revocation give owners control
- No public repo listing — anti-scraping by design
- Admin access protected upstream (Tailscale, VPN, Cloudflare Access)
Authentication
| Purpose | Method |
|---|---|
| User Identity | Forgejo Sessions |
| Data Access | Service Account PAT |
Tech Stack
- Backend: Python + FastAPI
- Frontend: Jinja2 templates + HTMX (no build step)
- Database: PostgreSQL
HTMX provides interactivity (filtering, form submissions) with minimal JavaScript. Jinja2 handles server-side rendering for fast page loads.
Quick Start
1. Run myst init
myst init
Prompts for:
- Public viewer URL (
share.example.com) - Private admin URL (
admin.example.com) - Forgejo base URL (
git.example.com) - PostgreSQL connection string
- Forgejo service account username and PAT
- Grant token secret
2. Configure Service Account
Create a dedicated Forgejo user (e.g., myst-bot) with a PAT:
read:userread:repository
3. Deploy
Deploy via Dokploy, Coolify, or your preferred platform.
Example Configuration
MYST_PUBLIC_URL="https://share.example.com"
MYST_ADMIN_URL="https://admin.example.com"
DATABASE_URL="postgresql://myst:secret@localhost:5432/myst"
FORGEJO_BASE_URL="https://git.example.com"
FORGEJO_SERVICE_ACCOUNT_USERNAME="myst-bot"
FORGEJO_PAT="fgp_xxxxxxxxxxxxxxxxxxxx"
GRANT_TOKEN_SECRET="your-secret-here"
Phase 1 Progress
- Project renamed from Embargo to Myst
- CLI scaffold (
myst init) - Config generation (
.env,myst.config.json) - Service foundation (FastAPI + PostgreSQL)
myst forgejo bootstrap— verify Forgejo connectivitymyst doctor— validate configurationmyst config print— show current config- Forgejo session authentication
- Repo ownership verification
- Private link creation (email-verified)
- Public link creation (time-expired)
- Web-based code viewer (Jinja2 + HTMX)
- User dashboard
- SMTP configuration UI
- Access logs