Compare commits

..

No commits in common. "aa71b2b6227ef6e0a06b6460c63c57c574f5056b" and "8e0c88bea86ef1d5e636572dee2953cee575f609" have entirely different histories.

3 changed files with 39 additions and 141 deletions

View file

@ -4,13 +4,35 @@
Myst is a companion service for Forgejo that lets repo owners create expiring, revocable, read-only share links for code snapshots.
## System Diagram
## Architecture
This diagram shows how traffic moves through the public internet, the VPS or self-hosted server, the host firewall, the platform router, Myst, Forgejo, and Postgres.
```mermaid
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
[![Myst system routing diagram](docs/diagrams/system-routing.svg)](docs/diagrams/system-routing.svg)
subgraph External["External"]
Owner["Repo Owner"]
Viewer["Link Recipient"]
end
Click the diagram to open the full-size SVG.
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
@ -34,7 +56,7 @@ Click the diagram to open the full-size SVG.
| Purpose | Method |
|---------|--------|
| User Identity | Forgejo Sessions |
| Data Access | Dedicated Forgejo User PAT |
| Data Access | Service Account PAT |
### Tech Stack
@ -58,10 +80,10 @@ Prompts for:
- Private admin URL (`admin.example.com`)
- Forgejo base URL (`git.example.com`)
- PostgreSQL connection string
- Dedicated Forgejo username and PAT
- Forgejo service account username and PAT
- Grant token secret
### 2. Configure Dedicated Forgejo User
### 2. Configure Service Account
Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT:
@ -70,12 +92,7 @@ Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT:
### 3. Deploy
Deploy Myst anywhere you can run a normal web app beside Forgejo. Phase 1 should explicitly support both of these examples:
- VPS deployment: Hostinger or another VPS with Dokploy, Traefik, UFW, Myst, Forgejo, and a shared Postgres instance that contains separate `forgejo` and `myst` databases.
- Self-hosted server deployment: a home server, mini PC, NAS, or other self-hosted Linux machine running Myst with Docker, Podman, Docker Compose, Coolify, Caddy, Nginx, or another reverse proxy.
Myst should not assume a VPS-only environment. The requirement is an existing Forgejo instance, Myst's own database, and a way to route the public and admin hostnames to the Myst app.
Deploy via Dokploy, Coolify, or your preferred platform.
## Example Configuration

File diff suppressed because one or more lines are too long

Before

Width:  |  Height:  |  Size: 36 KiB

View file

@ -52,7 +52,7 @@ Deployment boundaries:
- Forgejo is already running and is managed by the operator.
- Myst is deployed independently from Forgejo.
- Myst never reads or writes Forgejo's database directly.
- Myst uses a PAT created for a dedicated Forgejo user to call the Forgejo API.
- Myst uses a service account PAT to call the Forgejo API.
- Myst uses Forgejo sessions to identify logged-in users.
- Myst admin access is protected upstream rather than by an in-app login system in Phase 1.
- VPN, Tailscale, Cloudflare Access, or reverse-proxy auth is required for the admin surface in Phase 1.
@ -77,7 +77,7 @@ Users log in via Forgejo's existing session system:
- All Forgejo users with an account are trusted Myst users
- No separate user management in Myst
### Data Access: Dedicated Forgejo User PAT
### Data Access: Service Account PAT
Myst uses an operator-created PAT to call the Forgejo API:
@ -202,8 +202,8 @@ The CLI is the primary way to configure and validate Myst against an existing Fo
- prompt for the public viewer URL, for example `https://share.example.com`
- prompt for the private admin URL, for example `https://admin.example.com`
- prompt for the Forgejo base URL, for example `https://git.example.com`
- collect the dedicated Forgejo username Myst should use for API access, for example `myst-bot`
- collect a user-created Forgejo PAT for that dedicated Forgejo user
- collect the Forgejo service account username, for example `myst-bot`
- collect a user-created Forgejo PAT for that service account
- collect Myst Postgres connection details, for example `postgresql://myst:password@db.example.com:5432/myst`
- generate a grant token secret by default unless the operator pastes one
- generate all Myst-owned config files needed for deployment in Phase 1
@ -221,8 +221,8 @@ Suggested `init` prompt guidance:
- Private admin URL: "What private URL should operators use for the Myst admin UI?" Example: `https://admin.example.com`
- Forgejo base URL: "What is the base URL of your existing Forgejo instance?" Example: `https://git.example.com`
- Myst database URL: "What Postgres connection string should Myst use?" Example: `postgresql://myst:password@db.example.com:5432/myst`
- Dedicated Forgejo username: "What Forgejo username should Myst use for API access?" Example: `myst-bot`
- Forgejo PAT: "Paste the Forgejo personal access token for that dedicated Forgejo user" Example: `fgp_...`
- Forgejo service account username: "What Forgejo username should Myst use for API access?" Example: `myst-bot`
- Forgejo PAT: "Paste the Forgejo personal access token for that service account" Example: `fgp_...`
- Grant token secret: "Paste a grant token secret, or press enter to generate one automatically"
Suggested `init` prompt notes:
@ -246,10 +246,10 @@ Forgejo docs to link directly from CLI output:
`forgejo bootstrap` should:
- validate Forgejo connectivity
- validate the provided dedicated Forgejo user token
- validate the provided service account token
- verify minimum required scopes and permissions
- confirm Myst can resolve the repos it needs
- confirm the authenticated user matches the configured dedicated Forgejo username
- confirm the authenticated user matches the configured service account username
- confirm Myst can resolve a branch or ref to a pinned `commit_sha`
- confirm Myst can read tree and file data for a pinned commit
- verify Myst can confirm repo ownership for the operator's user account
@ -314,7 +314,7 @@ The owner dashboard provides:
- Link status (active, expired, revoked)
- View count and access logs (details to be finalized)
- Create new link flow:
- Select repo (fetched via the dedicated Forgejo user's PAT, filtered to owned repos)
- Select repo (fetched via service account PAT, filtered to owned repos)
- Select commit (branch/tag to SHA resolution)
- Choose link type (public or private)
- Set expiration