mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-20 12:03:30 +00:00
chore: rename all references from myst/embargo to firebreak
This commit is contained in:
parent
29687c8878
commit
1f20e64960
17 changed files with 149 additions and 155 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
|
@ -19,3 +19,6 @@ web/*.py[cod]
|
|||
# Tailwind standalone CLI
|
||||
web/tailwindcss
|
||||
web/app/static/css/output.css
|
||||
|
||||
# Playwright
|
||||
.playwright-mcp/
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ RUN pnpm install --frozen-lockfile
|
|||
|
||||
COPY . .
|
||||
|
||||
RUN pnpm -r --filter @myst/service build
|
||||
RUN pnpm -r --filter @firebreak/service build
|
||||
|
||||
ENV PORT=3000
|
||||
|
||||
|
|
@ -21,4 +21,4 @@ EXPOSE 3000
|
|||
|
||||
USER node
|
||||
|
||||
CMD ["pnpm", "--filter", "@myst/service", "start"]
|
||||
CMD ["pnpm", "--filter", "@firebreak/service", "start"]
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Myst UI Design
|
||||
# Firebreak UI Design
|
||||
|
||||
## Purpose
|
||||
|
||||
|
|
@ -7,7 +7,7 @@ Web application for creating secure, time-limited, view-only links to self-hoste
|
|||
## Pages
|
||||
|
||||
### Landing Page (`GET /`)
|
||||
- Explains Myst
|
||||
- Explains Firebreak
|
||||
- "Sign in with Forgejo" button
|
||||
- Nav shows Sign in (anonymous) or Dashboard/Logout (authenticated)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,21 +1,21 @@
|
|||
# Myst Auth and Deployment Design
|
||||
# Firebreak Auth and Deployment Design
|
||||
|
||||
This document captures current decisions about deployment topology, authentication, 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 Firebreak self-hosted and private by default.
|
||||
- Let operators attach Firebreak to an existing Forgejo deployment.
|
||||
- Expose only the read-only share-link viewer and Firebreak UI routes the operator chooses to publish.
|
||||
- Make the CLI responsible for Firebreak-specific configuration, validation, and Forgejo integration checks.
|
||||
- Keep Phase 1 scope minimal and shippable.
|
||||
- Prevent code theft and scraping by controlling who can view shared links and how.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Built-in admin authentication in Myst for Phase 1.
|
||||
- Built-in admin authentication in Firebreak for Phase 1.
|
||||
- Provisioning Forgejo for operators.
|
||||
- Provisioning PostgreSQL for Forgejo or Myst.
|
||||
- Provisioning PostgreSQL for Forgejo or Firebreak.
|
||||
- Owning reverse proxy, DNS, TLS, backup, or firewall setup.
|
||||
- Replacing Dokploy, Coolify, or any other hosting platform.
|
||||
- Adding a SaaS control plane.
|
||||
|
|
@ -24,7 +24,7 @@ This document captures current decisions about deployment topology, authenticati
|
|||
|
||||
## 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.
|
||||
Firebreak 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.
|
||||
|
||||
```ascii
|
||||
Public Internet
|
||||
|
|
@ -38,55 +38,55 @@ Myst is a companion service deployed beside an existing Forgejo instance. It own
|
|||
(Dokploy, Caddy, Nginx, etc.)
|
||||
|
|
||||
v
|
||||
Myst App (Viewer + Dashboard)
|
||||
Firebreak App (Viewer + Dashboard)
|
||||
|
|
||||
-------------------
|
||||
| |
|
||||
v v
|
||||
Myst Database Forgejo API
|
||||
Firebreak Database Forgejo API
|
||||
(Postgres) (existing instance)
|
||||
```ascii
|
||||
|
||||
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 Forgejo sessions to identify logged-in users.
|
||||
- Myst admin access is protected upstream rather than by an in-app login system in Phase 1.
|
||||
- Firebreak is deployed independently from Forgejo.
|
||||
- Firebreak never reads or writes Forgejo's database directly.
|
||||
- Firebreak uses a PAT created for a dedicated Forgejo user to call the Forgejo API.
|
||||
- Firebreak uses Forgejo sessions to identify logged-in users.
|
||||
- Firebreak 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.
|
||||
|
||||
## Authentication
|
||||
|
||||
Myst uses two authentication mechanisms for different purposes:
|
||||
Firebreak uses two authentication mechanisms for different purposes:
|
||||
|
||||
### User Identity: Forgejo Sessions
|
||||
|
||||
Users log in via Forgejo's existing session system:
|
||||
|
||||
1. User visits Myst dashboard
|
||||
2. Myst redirects to Forgejo login page
|
||||
1. User visits Firebreak dashboard
|
||||
2. Firebreak redirects to Forgejo login page
|
||||
3. User authenticates with Forgejo credentials
|
||||
4. Forgejo sets a session cookie
|
||||
5. Myst validates the session via Forgejo API
|
||||
6. Myst knows the user's identity without maintaining its own user database
|
||||
5. Firebreak validates the session via Forgejo API
|
||||
6. Firebreak knows the user's identity without maintaining its own user database
|
||||
|
||||
**Benefits:**
|
||||
- No separate Myst login — users use their existing Forgejo account
|
||||
- All Forgejo users with an account are trusted Myst users
|
||||
- No separate user management in Myst
|
||||
- No separate Firebreak login — users use their existing Forgejo account
|
||||
- All Forgejo users with an account are trusted Firebreak users
|
||||
- No separate user management in Firebreak
|
||||
|
||||
### Data Access: Dedicated Forgejo User PAT
|
||||
|
||||
Myst uses an operator-created PAT to call the Forgejo API:
|
||||
Firebreak uses an operator-created PAT to call the Forgejo API:
|
||||
|
||||
1. Verify repo ownership when owner creates a view link
|
||||
2. Fetch code content when serving view links to viewers
|
||||
|
||||
**Why both mechanisms?**
|
||||
- Sessions identify the user (zach@me.com is logged in)
|
||||
- PAT authorizes Myst's server-to-server API calls (fetch repo data, verify ownership)
|
||||
- PAT authorizes Firebreak's server-to-server API calls (fetch repo data, verify ownership)
|
||||
- PAT is not used for user identity — that's the session's job
|
||||
|
||||
## Link Types
|
||||
|
|
@ -99,12 +99,12 @@ Intended for sharing with specific individuals via email.
|
|||
- Owner selects repo and commit_sha
|
||||
- Owner enters recipient's email address
|
||||
- Owner sets expiration time
|
||||
- Myst generates a unique link token
|
||||
- Firebreak generates a unique link token
|
||||
|
||||
**Viewer flow:**
|
||||
1. Owner shares the link with the recipient (via email or copy)
|
||||
2. Recipient clicks the link
|
||||
3. Recipient enters email verification code from Myst's email
|
||||
3. Recipient enters email verification code from Firebreak's email
|
||||
4. On successful verification, recipient can view the code snapshot
|
||||
|
||||
**Protections:**
|
||||
|
|
@ -133,7 +133,7 @@ Intended for job applications, portfolios, and public sharing.
|
|||
|
||||
## Anti-Scraping Protections
|
||||
|
||||
Myst is designed to prevent code theft and scraping:
|
||||
Firebreak is designed to prevent code theft and scraping:
|
||||
|
||||
- No public listing of repositories
|
||||
- No profile exposure
|
||||
|
|
@ -144,7 +144,7 @@ Myst is designed to prevent code theft and scraping:
|
|||
|
||||
## Deployment
|
||||
|
||||
Myst should be deployable anywhere an operator can run a normal web app and Postgres database.
|
||||
Firebreak should be deployable anywhere an operator can run a normal web app and Postgres database.
|
||||
|
||||
Recommended v1 deployment environments:
|
||||
|
||||
|
|
@ -154,31 +154,31 @@ Recommended v1 deployment environments:
|
|||
|
||||
### Docker and Deployment
|
||||
|
||||
Myst provides a Dockerfile for containerized deployment:
|
||||
Firebreak 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
|
||||
- Firebreak includes a `Dockerfile` in its repository for building the container image
|
||||
- Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Firebreak container
|
||||
- Firebreak does not generate Docker Compose files for Forgejo or other infrastructure
|
||||
- Firebreak does not provision containers, images, or hosting resources
|
||||
- Operators manage their own container orchestration
|
||||
|
||||
For Dokploy users, deploying Myst is similar to deploying any other containerized application:
|
||||
For Dokploy users, deploying Firebreak 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`
|
||||
1. Build or import the Firebreak image using Dokploy's Docker Compose support
|
||||
2. Configure environment variables from `.env` generated by `firebreak init`
|
||||
3. Set up the public and admin domains in Dokploy's domain configuration
|
||||
4. Dokploy handles Traefik routing, TLS, and container restarts
|
||||
|
||||
### Database Configuration
|
||||
|
||||
Myst uses its own Postgres database on the same DB server as Forgejo:
|
||||
Firebreak uses its own Postgres database on the same DB server as Forgejo:
|
||||
|
||||
- Separate databases (e.g., `forgejo` and `myst`)
|
||||
- Separate databases (e.g., `forgejo` and `firebreak`)
|
||||
- NOT shared tables or schemas
|
||||
- Operators can run both on a small VPS efficiently
|
||||
- Independent backups and migrations
|
||||
|
||||
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.
|
||||
Admin access security is the operator's responsibility (VPN, firewall rules, SSO, host access, etc). Firebreak does not enforce or scaffold this in Phase 1.
|
||||
|
||||
Recommended admin protection modes:
|
||||
|
||||
|
|
@ -193,7 +193,7 @@ Recommended hostname split:
|
|||
|
||||
## CLI Responsibilities
|
||||
|
||||
The CLI is the primary way to configure and validate Myst against an existing Forgejo deployment.
|
||||
The CLI is the primary way to configure and validate Firebreak against an existing Forgejo deployment.
|
||||
|
||||
### `init`
|
||||
|
||||
|
|
@ -202,36 +202,36 @@ 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 the dedicated Forgejo username Firebreak should use for API access, for example `firebreak-bot`
|
||||
- collect a user-created Forgejo PAT for that dedicated Forgejo user
|
||||
- collect Myst Postgres connection details, for example `postgresql://myst:password@db.example.com:5432/myst`
|
||||
- collect Firebreak Postgres connection details, for example `postgresql://firebreak:password@db.example.com:5432/firebreak`
|
||||
- generate a grant token secret by default unless the operator pastes one
|
||||
- generate all Myst-owned config files needed for deployment in Phase 1
|
||||
- generate all Firebreak-owned config files needed for deployment in Phase 1
|
||||
- write `.env`
|
||||
- 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 init` in the directory where Myst will be deployed, usually on the target VPS or server workspace
|
||||
- remind operators to run `firebreak init` in the directory where Firebreak will be deployed, usually on the target VPS or server workspace
|
||||
|
||||
**Setup is manual** — operators enter all values directly. No auto-detection of Forgejo configuration.
|
||||
|
||||
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`
|
||||
- Private admin URL: "What private URL should operators use for the Firebreak 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`
|
||||
- Firebreak database URL: "What Postgres connection string should Firebreak use?" Example: `postgresql://firebreak:password@db.example.com:5432/firebreak`
|
||||
- Dedicated Forgejo username: "What Forgejo username should Firebreak use for API access?" Example: `firebreak-bot`
|
||||
- Forgejo PAT: "Paste the Forgejo personal access token for that dedicated Forgejo user" 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."
|
||||
- "Protect the admin URL upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth. Firebreak does not provide admin auth in Phase 1."
|
||||
- "Use a dedicated Forgejo user for Firebreak and create the PAT as that user."
|
||||
- "Recommended PAT scopes: `read:user`, `read:repository`; add `read:organization` only if your org or team setup requires it."
|
||||
- "Do not point Myst at Forgejo's database tables."
|
||||
- "Do not point Firebreak at Forgejo's database tables."
|
||||
- "Bare hostnames such as `share.example.com` are accepted and default to `https://`. Enter the full URL only if you need `http://` or a custom path."
|
||||
- "Run `myst init` in the directory where you plan to deploy Myst so the generated files are already in place on the target host."
|
||||
- "Run `firebreak init` in the directory where you plan to deploy Firebreak so the generated files are already in place on the target host."
|
||||
|
||||
Forgejo docs to link directly from CLI output:
|
||||
|
||||
|
|
@ -247,18 +247,18 @@ Forgejo docs to link directly from CLI output:
|
|||
- validate Forgejo connectivity
|
||||
- validate the provided dedicated Forgejo user token
|
||||
- verify minimum required scopes and permissions
|
||||
- confirm Myst can resolve the repos it needs
|
||||
- confirm Firebreak can resolve the repos it needs
|
||||
- confirm the authenticated user matches the configured dedicated Forgejo 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
|
||||
- confirm Firebreak can resolve a branch or ref to a pinned `commit_sha`
|
||||
- confirm Firebreak can read tree and file data for a pinned commit
|
||||
- verify Firebreak can confirm repo ownership for the operator's user account
|
||||
- never create Forgejo users, PATs, or repo permissions
|
||||
|
||||
### `doctor`
|
||||
|
||||
`doctor` should:
|
||||
|
||||
- validate the local Myst config
|
||||
- validate the local Firebreak config
|
||||
- validate database connectivity
|
||||
- validate Forgejo API reachability
|
||||
- validate token/scopes/permissions
|
||||
|
|
@ -268,7 +268,7 @@ Forgejo docs to link directly from CLI output:
|
|||
|
||||
`config print` should:
|
||||
|
||||
- show resolved Myst configuration
|
||||
- show resolved Firebreak configuration
|
||||
- redact secrets by default
|
||||
- help operators debug misconfiguration without touching infrastructure
|
||||
|
||||
|
|
@ -284,11 +284,11 @@ Forgejo docs to link directly from CLI output:
|
|||
Expected outputs from `init`:
|
||||
|
||||
- `.env`
|
||||
- optional platform templates for Myst only (e.g., Docker Compose for Dokploy)
|
||||
- optional platform templates for Firebreak only (e.g., Docker Compose for Dokploy)
|
||||
|
||||
## Data Model
|
||||
|
||||
Myst stores its metadata in its own Postgres database (separate from Forgejo's database).
|
||||
Firebreak stores its metadata in its own Postgres database (separate from Forgejo's database).
|
||||
|
||||
Minimum v1 data model:
|
||||
|
||||
|
|
@ -352,8 +352,8 @@ Active surfaces:
|
|||
|
||||
Next implementation work:
|
||||
|
||||
1. Narrow `init` to Myst-only config generation for an existing Forgejo deployment
|
||||
2. Add config types for Forgejo connection details, Myst base URL, database, and SMTP settings
|
||||
1. Narrow `init` to Firebreak-only config generation for an existing Forgejo deployment
|
||||
2. Add config types for Forgejo connection details, Firebreak base URL, database, and SMTP settings
|
||||
3. Implement `forgejo bootstrap` and `doctor`
|
||||
4. Add Postgres-backed service foundation using the data model
|
||||
5. Wire the service to load generated config and validate required env at startup
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
# Myst Phase 1 Design
|
||||
# Firebreak Phase 1 Design
|
||||
|
||||
This document captures the approved Phase 1 plan for Myst.
|
||||
This document captures the approved Phase 1 plan for Firebreak.
|
||||
|
||||
## Scope
|
||||
|
||||
Phase 1 delivers:
|
||||
|
||||
- CLI setup for attaching Myst to an existing Forgejo deployment
|
||||
- Myst service foundation
|
||||
- CLI setup for attaching Firebreak to an existing Forgejo deployment
|
||||
- Firebreak service foundation
|
||||
- constrained Forgejo service-account integration
|
||||
- immutable snapshot grants pinned to `commit_sha`
|
||||
- owner dashboard and viewer flow
|
||||
|
|
@ -48,46 +48,46 @@ Phase 1 does not deliver:
|
|||
## Security Baseline
|
||||
|
||||
- dedicated Forgejo user access is restricted to approved repos
|
||||
- Myst grant checks are enforced on every Forgejo read
|
||||
- Firebreak 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
|
||||
- Firebreak 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
|
||||
- Firebreak does not ship built-in admin auth in Phase 1
|
||||
|
||||
## Authentication Model
|
||||
|
||||
Myst uses two authentication mechanisms:
|
||||
Firebreak 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
|
||||
- Firebreak redirects to Forgejo login and validates the session
|
||||
- Users use their existing Forgejo accounts — no separate Firebreak login
|
||||
- All Forgejo users with an account are trusted Firebreak users
|
||||
|
||||
**Data Access (Dedicated Forgejo User PAT)**
|
||||
- Myst uses an operator-created PAT for a dedicated Forgejo user to call the Forgejo API
|
||||
- Firebreak 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)
|
||||
- PAT allows Firebreak to verify repo ownership (can zach@me.com create view links for this repo?)
|
||||
- PAT allows Firebreak 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 dedicated Forgejo user is a normal Forgejo user account dedicated to Firebreak, such as `firebreak-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
|
||||
- Firebreak must not create Forgejo users, PATs, or repo permissions in Phase 1
|
||||
|
||||
## Link Types
|
||||
|
||||
Myst supports two types of view links:
|
||||
Firebreak supports two types of view links:
|
||||
|
||||
### Private Links (Email-Verified)
|
||||
|
||||
|
|
@ -96,7 +96,7 @@ Myst supports two types of view links:
|
|||
- 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
|
||||
- Firebreak sends an email with a verification code
|
||||
- Viewer enters the code to access the snapshot
|
||||
|
||||
### Public Links (Time-Expired)
|
||||
|
|
@ -112,32 +112,32 @@ Myst supports two types of view links:
|
|||
|
||||
Only repo owners can create view links for their repos.
|
||||
|
||||
- Myst verifies ownership via the Forgejo API using the dedicated Forgejo user PAT
|
||||
- Firebreak 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:
|
||||
`firebreak 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`
|
||||
- private admin URL, for example `https://admin.example.com` or `https://firebreak-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`
|
||||
- Firebreak Postgres URL, for example `postgresql://firebreak:password@db.example.com:5432/firebreak`
|
||||
- Forgejo bot username, for example `firebreak-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:
|
||||
`firebreak init` should generate all Firebreak-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
|
||||
- any future Firebreak-only deployment templates, but never Forgejo provisioning files
|
||||
|
||||
`myst init` should provide inline guidance that:
|
||||
`firebreak 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
|
||||
- it should be run in the directory where Firebreak will be deployed, usually on the target VPS or server workspace
|
||||
- the admin URL must be protected upstream because Firebreak does not provide admin auth in Phase 1
|
||||
- the database URL must point to Firebreak'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://`
|
||||
|
|
@ -145,35 +145,35 @@ Only repo owners can create view links for their repos.
|
|||
## 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
|
||||
- Firebreak is deployed independently as its own app
|
||||
- Firebreak uses its own Postgres database on the same DB server as Forgejo (separate database, not shared tables)
|
||||
- Firebreak 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
|
||||
- the Firebreak 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:
|
||||
Firebreak 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
|
||||
- Firebreak includes a `Dockerfile` in its repository for building the container image
|
||||
- Operators use their preferred platform (Dokploy, Coolify, manual Docker, etc.) to deploy the Firebreak container
|
||||
- Firebreak does not generate Docker Compose files for Forgejo or other infrastructure
|
||||
- Firebreak 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:
|
||||
For Dokploy users, deploying Firebreak 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`
|
||||
1. Build or import the Firebreak image using Dokploy's Docker Compose support
|
||||
2. Configure environment variables from `.env` generated by `firebreak 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:
|
||||
Firebreak 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
|
||||
- recommended: same PostgreSQL instance with `forgejo` and `firebreak` 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
|
||||
|
|
@ -187,14 +187,14 @@ Minimum v1 data model:
|
|||
|
||||
## Forgejo Bootstrap Baseline
|
||||
|
||||
`myst forgejo bootstrap` should verify, not provision:
|
||||
`firebreak 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
|
||||
- minimum token scopes are sufficient for Firebreak's read-only API usage
|
||||
- Firebreak can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve
|
||||
- Firebreak can verify repo ownership for the operator's user account
|
||||
|
||||
## Viewer Baseline
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Application
|
||||
APP_NAME=Myst
|
||||
APP_NAME=Firebreak
|
||||
|
||||
# Database (Docker Compose auto-configures this)
|
||||
DATABASE_URL=postgresql+asyncpg://myst:myst@db:5432/myst_db
|
||||
DATABASE_URL=postgresql+asyncpg://firebreak:firebreak@db:5432/firebreak_db
|
||||
|
||||
# Forgejo
|
||||
FORGEJO_BASE_URL=
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"name": "myst",
|
||||
"name": "firebreak",
|
||||
"private": true,
|
||||
"version": "0.1.0",
|
||||
"packageManager": "pnpm@10.33.0",
|
||||
|
|
|
|||
|
|
@ -1,19 +1,19 @@
|
|||
{
|
||||
"name": "@myst/cli",
|
||||
"description": "CLI for configuring and verifying Myst with Forgejo",
|
||||
"name": "@firebreak/cli",
|
||||
"description": "CLI for configuring and verifying Firebreak with Forgejo",
|
||||
"version": "0.1.0",
|
||||
"author": {
|
||||
"name": "Zach Tatman",
|
||||
"email": "zach.tatman.dev@gmail.com"
|
||||
},
|
||||
"bugs": {
|
||||
"url": "https://github.com/ZTatman/myst/issues"
|
||||
"url": "https://github.com/ZTatman/firebreak/issues"
|
||||
},
|
||||
"homepage": "https://github.com/ZTatman/myst#readme",
|
||||
"homepage": "https://github.com/ZTatman/firebreak#readme",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"bin": {
|
||||
"myst": "./dist/index.js"
|
||||
"firebreak": "./dist/index.js"
|
||||
},
|
||||
"scripts": {
|
||||
"build": "tsc -p tsconfig.json",
|
||||
|
|
|
|||
|
|
@ -53,12 +53,12 @@ function showHelp(registry: CommandRegistry, description: string): void {
|
|||
const colWidth = Math.max(...allRows.map((r) => r.name.length)) + PADDING;
|
||||
|
||||
const lines: string[] = [];
|
||||
lines.push(c.yellow("myst"));
|
||||
lines.push(c.yellow("firebreak"));
|
||||
lines.push("");
|
||||
lines.push(`${INDENT}${description}`);
|
||||
lines.push("");
|
||||
lines.push(c.bold("Usage:"));
|
||||
lines.push(`${INDENT}myst <command> [options]`);
|
||||
lines.push(`${INDENT}firebreak <command> [options]`);
|
||||
lines.push("");
|
||||
|
||||
lines.push(c.bold("Commands:"));
|
||||
|
|
@ -99,7 +99,7 @@ function showCommandHelp(
|
|||
const lines: string[] = [];
|
||||
|
||||
const fullName = subcommand ? `${command} ${subcommand}` : command;
|
||||
lines.push(c.yellow("myst " + fullName));
|
||||
lines.push(c.yellow("firebreak " + fullName));
|
||||
lines.push("");
|
||||
|
||||
if (targetConf.description) {
|
||||
|
|
@ -112,8 +112,8 @@ function showCommandHelp(
|
|||
const usageCmd = subcommand ? `${command} ${subcommand}` : command;
|
||||
const usageLine =
|
||||
hasSubcommands && !subcommand
|
||||
? `myst ${command} <subcommand> [options]`
|
||||
: `myst ${usageCmd} [options]`;
|
||||
? `firebreak ${command} <subcommand> [options]`
|
||||
: `firebreak ${usageCmd} [options]`;
|
||||
lines.push(c.bold("Usage:"));
|
||||
lines.push(`${INDENT}${usageLine}`);
|
||||
lines.push("");
|
||||
|
|
@ -201,7 +201,7 @@ export async function runCli(
|
|||
const subcommand = argv[1] ?? "";
|
||||
const remainingArgs = argv.slice(2);
|
||||
|
||||
// If user types myst -h or --help with a command
|
||||
// If user types firebreak -h or --help with a command
|
||||
const wantsCommandHelp =
|
||||
isHelpFlag(subcommand) || remainingArgs.some(isHelpFlag);
|
||||
|
||||
|
|
|
|||
|
|
@ -36,10 +36,10 @@ function validateHttpUrlOrHost(
|
|||
}
|
||||
|
||||
async function init(opts: { output?: string }) {
|
||||
p.intro(c.bold("myst config init"));
|
||||
p.intro(c.bold("firebreak config init"));
|
||||
p.note(
|
||||
[
|
||||
`${c.bold("Run this in the directory where you plan to deploy Myst.")}`,
|
||||
`${c.bold("Run this in the directory where you plan to deploy Firebreak.")}`,
|
||||
"",
|
||||
c.bold("Forgejo docs:"),
|
||||
"",
|
||||
|
|
@ -116,7 +116,7 @@ async function init(opts: { output?: string }) {
|
|||
forgejoBaseUrl: () =>
|
||||
p.text({
|
||||
message:
|
||||
"Forgejo API URL (how Myst reaches Forgejo, not your browser URL)?",
|
||||
"Forgejo API URL (how Firebreak reaches Forgejo, not your browser URL)?",
|
||||
placeholder: "http://forgejo:3000",
|
||||
validate: (v) => validateHttpUrlOrHost(v, "Forgejo base URL"),
|
||||
}),
|
||||
|
|
@ -171,19 +171,19 @@ async function init(opts: { output?: string }) {
|
|||
[
|
||||
`${c.bold("Forgejo API URL:")} ${c.cyan(forgejoBaseUrl)}`,
|
||||
"",
|
||||
`Myst will use this URL to call Forgejo's API.`,
|
||||
`Firebreak will use this URL to call Forgejo's API.`,
|
||||
`- Docker (same Compose network): http://forgejo:3000`,
|
||||
`- Bare metal / non-container: http://localhost:3000`,
|
||||
`- Cross-host deployment: https://git.example.com`,
|
||||
].join("\n"),
|
||||
);
|
||||
p.log.success(
|
||||
"Done. Verify myst's connection using the 'verify' command.\nOnce verified, deploy!",
|
||||
"Done. Verify firebreak's connection using the 'verify' command.\nOnce verified, deploy!",
|
||||
);
|
||||
} catch (error) {
|
||||
s.stop();
|
||||
p.cancel(
|
||||
error instanceof Error ? error.message : "Failed to initialize Myst",
|
||||
error instanceof Error ? error.message : "Failed to initialize Firebreak",
|
||||
);
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ import * as c from "yoctocolors";
|
|||
|
||||
import {
|
||||
ENV_MAPPING,
|
||||
MystEnvironmentVariables,
|
||||
FirebreakEnvironmentVariables,
|
||||
parseEnvFile,
|
||||
SECRET_KEYS,
|
||||
} from "../../utils/config.js";
|
||||
|
|
@ -15,7 +15,7 @@ export const commandConfig: CommandConfig = {
|
|||
handler: async () => {
|
||||
const envPath = path.join(process.cwd(), ".env");
|
||||
|
||||
let config: Partial<MystEnvironmentVariables>;
|
||||
let config: Partial<FirebreakEnvironmentVariables>;
|
||||
|
||||
try {
|
||||
config = parseEnvFile(envPath);
|
||||
|
|
@ -31,7 +31,7 @@ export const commandConfig: CommandConfig = {
|
|||
throw error;
|
||||
}
|
||||
|
||||
process.stdout.write(c.bold("Myst Configuration\n"));
|
||||
process.stdout.write(c.bold("Firebreak Configuration\n"));
|
||||
process.stdout.write(`${c.dim("─".repeat(40))}\n`);
|
||||
|
||||
for (const [envKey, configKey] of Object.entries(ENV_MAPPING)) {
|
||||
|
|
|
|||
|
|
@ -162,7 +162,7 @@ async function runForgejoChecks(
|
|||
|
||||
async function verifyCommand(opts: VerifyOptions): Promise<void> {
|
||||
const isDiagnostic = opts.diagnostic ?? false;
|
||||
p.intro(c.bold("myst verify"));
|
||||
p.intro(c.bold("firebreak verify"));
|
||||
|
||||
const config = loadConfig();
|
||||
if (!config) {
|
||||
|
|
@ -179,7 +179,7 @@ async function verifyCommand(opts: VerifyOptions): Promise<void> {
|
|||
}
|
||||
|
||||
export const commandConfig: CommandConfig = {
|
||||
description: "Verify Myst configuration and connection to Forgejo",
|
||||
description: "Verify Firebreak configuration and connection to Forgejo",
|
||||
options: {
|
||||
diagnostic: {
|
||||
type: "boolean",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
import fs from "node:fs";
|
||||
|
||||
export interface MystEnvironmentVariables {
|
||||
export interface FirebreakEnvironmentVariables {
|
||||
forgejoBaseUrl: string;
|
||||
forgejoPat: string;
|
||||
}
|
||||
|
|
@ -18,8 +18,8 @@ export const SECRET_ENV_KEYS = ["FORGEJO_PAT"] as const;
|
|||
|
||||
export function parseEnvFile(
|
||||
envPath: string,
|
||||
): Partial<MystEnvironmentVariables> {
|
||||
const config: Partial<MystEnvironmentVariables> = {};
|
||||
): Partial<FirebreakEnvironmentVariables> {
|
||||
const config: Partial<FirebreakEnvironmentVariables> = {};
|
||||
const content = fs.readFileSync(envPath, "utf-8");
|
||||
const lines = content.split("\n");
|
||||
|
||||
|
|
@ -41,9 +41,9 @@ export function parseEnvFile(
|
|||
return config;
|
||||
}
|
||||
|
||||
export function generateEnvFile(options: MystEnvironmentVariables): string {
|
||||
export function generateEnvFile(options: FirebreakEnvironmentVariables): string {
|
||||
const lines = [
|
||||
`# Forgejo API endpoint that Myst calls.`,
|
||||
`# Forgejo API endpoint that Firebreak calls.`,
|
||||
`# Docker (same Compose network): http://forgejo:3000`,
|
||||
`# Bare metal / non-container: http://localhost:3000`,
|
||||
`# Cross-host: https://git.example.com`,
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"name": "@myst/shared",
|
||||
"name": "@firebreak/shared",
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
export const MYST_DEFAULT_SERVICE_PORT = 4000;
|
||||
export const FIREBREAK_DEFAULT_SERVICE_PORT = 4000;
|
||||
|
|
|
|||
9
pnpm-lock.yaml
generated
9
pnpm-lock.yaml
generated
|
|
@ -20,19 +20,10 @@ importers:
|
|||
'@clack/prompts':
|
||||
specifier: ^1.2.0
|
||||
version: 1.2.0
|
||||
'@myst/shared':
|
||||
specifier: workspace:*
|
||||
version: link:../shared
|
||||
yoctocolors:
|
||||
specifier: ^2.1.2
|
||||
version: 2.1.2
|
||||
|
||||
packages/service:
|
||||
dependencies:
|
||||
'@myst/shared':
|
||||
specifier: workspace:*
|
||||
version: link:../shared
|
||||
|
||||
packages/shared: {}
|
||||
|
||||
packages:
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
"lib": ["ES2022"],
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"@myst/shared": ["packages/shared/src/index.ts"]
|
||||
"@firebreak/shared": ["packages/shared/src/index.ts"]
|
||||
},
|
||||
"strict": true,
|
||||
"skipLibCheck": true,
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue