8.9 KiB
Myst Auth and Deployment Design
This document captures current decisions about deployment topology and CLI scope for Phase 1.
Goals
- Keep Myst self-hosted and private by default.
- Let operators attach Myst to an existing Forgejo deployment.
- Expose only the read-only share-link viewer and Myst UI routes the operator chooses to publish.
- Make the CLI responsible for Myst-specific configuration, validation, and Forgejo integration checks.
- Keep Phase 1 scope minimal and shippable.
Non-Goals
- Built-in admin authentication in Myst for Phase 1.
- Provisioning Forgejo for operators.
- Provisioning PostgreSQL for Forgejo or Myst.
- Owning reverse proxy, DNS, TLS, backup, or firewall setup.
- Replacing Coolify or any other hosting platform.
- Adding a SaaS control plane.
- Requiring end users to join Tailscale in order to view shared code.
- Designing a browser-based admin UX before the backend and integration flow exist.
Core Architecture
Myst is a companion service deployed beside an existing Forgejo instance. It owns its own UI/API app and its own database, and it integrates with Forgejo only through the Forgejo API.
Public Internet
|
v
DNS: myst.example.com
|
v
Reverse Proxy / Platform Router
(Coolify, Caddy, Nginx, etc.)
|
v
Myst App (UI + API)
|
-------------------
| |
v v
Myst Database Forgejo API
(Postgres) (existing instance)
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 authenticates to Forgejo with an operator-created service account token.
- 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.
Deployment
Myst should be deployable anywhere an operator can run a normal web app and Postgres database.
Recommended v1 deployment environments:
- Same VPS or host as Forgejo
- Same Coolify project or private network as Forgejo
- Separate host on the same trusted network as Forgejo
Admin access security is the operator's responsibility (VPN, firewall rules, SSO, host access, etc). Myst does not enforce or scaffold this in Phase 1.
Recommended admin protection modes:
- Tailscale or another private network
- Cloudflare Access or similar identity-aware proxy
- Reverse-proxy basic auth or IP allowlisting when the operator accepts the trade-offs
Recommended hostname split:
https://share.example.comfor the public viewerhttps://admin.example.comfor the private admin UI
Public Viewer Rules
- Share links are public resources by design.
- Public access must be read-only.
- Public access must not expose database ports or Forgejo admin surfaces.
- Viewer requests must validate:
- link token
- expiration
- revoked state
- snapshot binding
The viewer should be the only public application surface that emits code content.
CLI Responsibilities
The CLI is the primary way to configure and validate Myst against an existing Forgejo deployment.
init
init should:
- 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 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
- write
.env - write
myst.config.json - print manual follow-up actions for admin URL protection, app deployment, and Forgejo validation
- show links to Forgejo docs for API usage, token scopes, repo permissions, and the admin CLI
- remind operators to run
myst initin the directory where Myst will be deployed, usually on the target VPS or server workspace
Suggested init prompt guidance:
- Public viewer URL: "What public URL should viewers use for shared links?" Example:
https://share.example.com - 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 - 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:
- "Protect the admin URL upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth. Myst does not provide admin auth in Phase 1."
- "Use a dedicated Forgejo user for Myst and create the PAT as that user."
- "Recommended PAT scopes:
read:user,read:repository; addread:organizationonly if your org or team setup requires it." - "Do not point Myst at Forgejo's database tables."
- "Bare hostnames such as
share.example.comare accepted and default tohttps://. Enter the full URL only if you needhttp://or a custom path." - "Run
myst initin the directory where you plan to deploy Myst so the generated files are already in place on the target host."
Forgejo docs to link directly from CLI output:
https://forgejo.org/docs/latest/user/api-usage/https://forgejo.org/docs/latest/user/token-scope/https://forgejo.org/docs/latest/user/repo-permissions/https://forgejo.org/docs/latest/admin/command-line/
forgejo bootstrap
forgejo bootstrap should:
- validate Forgejo connectivity
- 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 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
- never create Forgejo users, PATs, or repo permissions
doctor
doctor should:
- validate the local Myst config
- validate database connectivity
- validate Forgejo API reachability
- validate token/scopes/permissions
- validate the public base URL and key route assumptions
config print
config print should:
- show resolved Myst configuration
- redact secrets by default
- help operators debug misconfiguration without touching infrastructure
CLI UX
- Use spinners for long-running steps.
- Use prompts for interactive configuration.
- Keep output terse and actionable.
- Present required manual follow-up actions clearly after initialization.
Configuration Outputs
Expected outputs from init:
.envmyst.config.json- optional platform templates for Myst only
Data and Auth Model
- Share links are tied to immutable snapshots.
- Grants must resolve to a specific
commit_sha. - Viewer endpoints must never accept arbitrary repo/ref selection.
- Myst stores its metadata in its own Postgres database.
- Minimum v1 data model is
reposandgrants. - Operators create the Forgejo service account and PAT themselves.
- Myst does not maintain a separate in-app admin user database in Phase 1.
- Admin access is delegated to operator-managed network or reverse-proxy controls.
Repo Implementation Impact
Active surfaces:
- CLI entrypoint:
packages/cli/src/index.ts - Command stubs:
packages/cli/src/commands/* - Config generators:
packages/cli/src/generators/* - Shared constants/types:
packages/shared/src/* - Service entrypoint:
packages/service/src/index.ts
Next implementation work:
- Narrow
initto Myst-only config generation for an existing Forgejo deployment - Add config types for Forgejo connection details, Myst base URL, and database settings
- Implement
forgejo bootstrapanddoctor - Add Postgres-backed service foundation using the minimum
reposandgrantsschema - Wire the service to load generated config and validate required env at startup
Open Questions
- Should the public viewer be mounted at a fixed path like
/share/*or a dedicated hostname? - Should the admin UI and viewer share a single Myst origin in v1, or should the docs recommend separate admin and public origins?