- Centralize examples in /examples folder - Fix README broken reference to docker-compose.example.yml - Rename design docs (remove date prefixes)
222 lines
8.9 KiB
Markdown
222 lines
8.9 KiB
Markdown
# Myst Phase 1 Design
|
|
|
|
This document captures the approved Phase 1 plan for Myst.
|
|
|
|
## Scope
|
|
|
|
Phase 1 delivers:
|
|
|
|
- CLI setup for attaching Myst to an existing Forgejo deployment
|
|
- Myst service foundation
|
|
- constrained Forgejo service-account integration
|
|
- immutable snapshot grants pinned to `commit_sha`
|
|
- owner dashboard and viewer flow
|
|
- two link types: private (email-verified) and public (time-expired)
|
|
- web-based code viewer (not git clone URLs)
|
|
|
|
Phase 1 does not deliver:
|
|
|
|
- Forgejo provisioning
|
|
- Forgejo database provisioning
|
|
- reverse proxy or DNS automation
|
|
- platform-specific hosting orchestration beyond optional templates and docs
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Python 3.11+ with FastAPI
|
|
- **Frontend**: Jinja2 templates with HTMX for interactivity
|
|
- **Database**: PostgreSQL
|
|
- **Async**: Uses `async/await` with asyncpg for database access
|
|
|
|
### Why This Stack?
|
|
|
|
**FastAPI**: Lightweight async framework, automatic OpenAPI docs, Pydantic for validation.
|
|
|
|
**Jinja2 + HTMX**: Server-side rendering with minimal JavaScript. HTMX handles dynamic updates (filtering, form submissions) without a build step or heavy SPA framework.
|
|
|
|
**PostgreSQL**: Reliable, well-supported by async libraries (asyncpg, SQLModel).
|
|
|
|
## Reviewable Branches
|
|
|
|
1. `codex/phase1-bootstrap-monorepo`
|
|
2. `codex/phase1-cli-init-skeleton`
|
|
3. `codex/phase1-service-foundation`
|
|
4. `codex/phase1-forgejo-integration`
|
|
5. `codex/phase1-grants-viewer`
|
|
6. `codex/phase1-dashboard-logs-settings`
|
|
|
|
## Security Baseline
|
|
|
|
- dedicated Forgejo user access is restricted to approved repos
|
|
- Myst grant checks are enforced on every Forgejo read
|
|
- grants store `repo_id` and pinned `commit_sha`
|
|
- viewer requests never choose repo or ref directly
|
|
- operators create the dedicated Forgejo user and PAT themselves
|
|
- Myst stores only its own app config and metadata in its own database
|
|
- admin access is protected upstream with Tailscale, VPN, Cloudflare Access, reverse-proxy auth, or equivalent operator-managed controls
|
|
- Myst does not ship built-in admin auth in Phase 1
|
|
|
|
## Authentication Model
|
|
|
|
Myst uses two authentication mechanisms:
|
|
|
|
**User Identity (Forgejo Sessions)**
|
|
- Users log in via Forgejo's session system
|
|
- Myst redirects to Forgejo login and validates the session
|
|
- Users use their existing Forgejo accounts — no separate Myst login
|
|
- All Forgejo users with an account are trusted Myst users
|
|
|
|
**Data Access (Dedicated Forgejo User PAT)**
|
|
- Myst uses an operator-created PAT for a dedicated Forgejo user to call the Forgejo API
|
|
- PAT is used to verify repo ownership and fetch code for viewers
|
|
- PAT is never used for user identity (that's handled by sessions)
|
|
|
|
**Why both?**
|
|
- Sessions identify who the user is (zach@me.com logged in)
|
|
- PAT allows Myst to verify repo ownership (can zach@me.com create view links for this repo?)
|
|
- PAT allows Myst to fetch code content for the viewer (get the pinned commit's files)
|
|
|
|
## Dedicated Forgejo User Baseline
|
|
|
|
- the dedicated Forgejo user is a normal Forgejo user account dedicated to Myst, such as `myst-bot`
|
|
- the operator creates this user in Forgejo and grants repo access explicitly
|
|
- the operator creates the PAT for this user through the Forgejo UI or admin CLI
|
|
- recommended PAT scopes are `read:user` and `read:repository`
|
|
- `read:organization` may also be required when repo visibility depends on org or team APIs
|
|
- Myst must not create Forgejo users, PATs, or repo permissions in Phase 1
|
|
|
|
## Link Types
|
|
|
|
Myst supports two types of view links:
|
|
|
|
### Private Links (Email-Verified)
|
|
|
|
- Time expired (configurable duration)
|
|
- Revocable by the owner
|
|
- Requires email verification code to view
|
|
- Tied to a specific email address
|
|
- Owner specifies the recipient's email when creating the link
|
|
- Myst sends an email with a verification code
|
|
- Viewer enters the code to access the snapshot
|
|
|
|
### Public Links (Time-Expired)
|
|
|
|
- Time expired (configurable duration)
|
|
- Revocable by the owner
|
|
- No verification required
|
|
- Anyone with the link can view
|
|
- Suitable for job application portfolio fields
|
|
- Owner copies the link and shares it directly
|
|
|
|
## Link Creation Rules
|
|
|
|
Only repo owners can create view links for their repos.
|
|
|
|
- Myst verifies ownership via the Forgejo API using the dedicated Forgejo user PAT
|
|
- Collaborators or read-access users cannot create view links
|
|
- Site admins are treated as regular users for this purpose (details to be finalized)
|
|
|
|
## CLI Init Baseline
|
|
|
|
`myst init` should ask only for:
|
|
|
|
- public viewer URL, for example `https://share.example.com`
|
|
- private admin URL, for example `https://admin.example.com` or `https://myst-admin.tailnet.ts.net`
|
|
- Forgejo base URL, for example `https://git.example.com`
|
|
- Myst Postgres URL, for example `postgresql://myst:password@db.example.com:5432/myst`
|
|
- Forgejo bot username, for example `myst-bot`
|
|
- Forgejo PAT for that dedicated Forgejo user
|
|
- grant token secret, with secure auto-generation as the default
|
|
|
|
`myst init` should generate all Myst-owned deployment config needed for Phase 1:
|
|
|
|
- `.env` (environment variables for Docker/container deployment)
|
|
- any future Myst-only deployment templates, but never Forgejo provisioning files
|
|
|
|
`myst init` should provide inline guidance that:
|
|
|
|
- it should be run in the directory where Myst will be deployed, usually on the target VPS or server workspace
|
|
- the admin URL must be protected upstream because Myst does not provide admin auth in Phase 1
|
|
- the database URL must point to Myst's own Postgres database, not Forgejo's tables
|
|
- the PAT should be created for the dedicated Forgejo user
|
|
- the operator can consult Forgejo docs for token creation and scopes if needed
|
|
- bare hostnames such as `share.example.com` are accepted and should default to `https://`
|
|
|
|
## Deployment Baseline
|
|
|
|
- Forgejo is already deployed and operator-managed
|
|
- Myst is deployed independently as its own app
|
|
- Myst uses its own Postgres database on the same DB server as Forgejo (separate database, not shared tables)
|
|
- Myst reaches Forgejo via API using a least-privilege PAT for the dedicated Forgejo user
|
|
- the CLI validates configuration and connectivity rather than provisioning infrastructure
|
|
- the Myst admin surface must be protected by VPN, Tailscale, Cloudflare Access, or reverse-proxy auth in front of the app
|
|
|
|
### Docker and Deployment
|
|
|
|
Myst provides a Dockerfile for containerized deployment:
|
|
|
|
- Myst includes a `Dockerfile` in its repository for building the container image
|
|
- Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Myst container
|
|
- Myst does not generate Docker Compose files for Forgejo or other infrastructure
|
|
- Myst does not provision containers, images, or hosting resources
|
|
- Operators manage their own container orchestration (Dokploy handles this for most users)
|
|
|
|
For Dokploy users, deploying Myst is similar to deploying any other containerized application:
|
|
|
|
1. Build or import the Myst image using Dokploy's Docker Compose support
|
|
2. Configure environment variables from `.env` generated by `myst init`
|
|
3. Set up the public and admin domains in Dokploy's domain configuration
|
|
4. Dokploy handles Traefik routing, TLS, and container restarts
|
|
|
|
## Database Model
|
|
|
|
Myst uses its own Postgres database on the same DB server as Forgejo:
|
|
|
|
- separate databases (not shared tables with Forgejo)
|
|
- recommended: same PostgreSQL instance with `forgejo` and `myst` databases
|
|
- clean schema separation prevents coupling to Forgejo's database schema
|
|
- independent backups and migrations
|
|
- operators can run both databases on a small VPS efficiently
|
|
|
|
Minimum v1 data model:
|
|
|
|
- `grants`: view link metadata (repo, commit_sha, type, expiration, email, revoked)
|
|
- `verification_codes`: email verification codes for private links
|
|
- `sessions`: user sessions (validated against Forgejo)
|
|
- `smtp_config`: SMTP settings (encrypted)
|
|
|
|
## Forgejo Bootstrap Baseline
|
|
|
|
`myst forgejo bootstrap` should verify, not provision:
|
|
|
|
- Forgejo base URL reachability
|
|
- dedicated Forgejo user token validity
|
|
- authenticated user matches the configured Forgejo bot username
|
|
- minimum token scopes are sufficient for Myst's read-only API usage
|
|
- Myst can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve
|
|
- Myst can verify repo ownership for the operator's user account
|
|
|
|
## Viewer Baseline
|
|
|
|
The web-based viewer is the public-facing code display surface:
|
|
|
|
- displays code with syntax highlighting
|
|
- read-only, no raw git access
|
|
- validates link token, expiration, and revoked state
|
|
- for private links: requires valid email verification code
|
|
- for public links: accessible immediately with the link
|
|
- never exposes Forgejo admin surfaces or database ports
|
|
- pinned to immutable commit_sha (not moving branches)
|
|
|
|
## User Dashboard
|
|
|
|
The owner dashboard allows repo owners to manage their view links:
|
|
|
|
- list of created links (public and private)
|
|
- link status (active, expired, revoked)
|
|
- view count and access logs (details to be finalized)
|
|
- create new link flow
|
|
- revoke/delete existing links
|
|
- SMTP configuration page
|
|
|
|
First-time users see a quick setup page to configure SMTP credentials before accessing the full dashboard.
|