diff --git a/README.md b/README.md index 1b515ee..1e1accb 100644 --- a/README.md +++ b/README.md @@ -54,23 +54,23 @@ myst config init Prompts for: -- Public viewer URL (`share.example.com`) -- Private admin URL (`admin.example.com`) -- Forgejo base URL (`git.example.com`) -- PostgreSQL connection string -- Dedicated Forgejo username and PAT -- Grant token secret +- Forgejo API URL — internal address when co-located (`http://forgejo:3000`) or public URL for cross-host (`https://git.example.com`) +- Forgejo PAT (with `read:user` and `read:repository` scopes) -### 2. Configure Dedicated Forgejo User +### 2. Deploy with Docker Compose -Create a dedicated Forgejo user (e.g., `myst-bot`) with a PAT: +```bash +cd packages/cli/examples +cp docker-compose.example.yml docker-compose.yml +# Edit .env with your FORGEJO_BASE_URL and FORGEJO_PAT +docker compose up -d +``` -- `read:user` -- `read:repository` +The DATABASE_URL is injected automatically by Docker Compose. -### 3. Deploy +### 3. Alternative Deployments -Deploy Myst anywhere you can run a normal web app beside Forgejo. Phase 1 should explicitly support both of these examples: +For non-Docker deployments, you must supply DATABASE_URL yourself: - 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. @@ -79,16 +79,18 @@ Myst should not assume a VPS-only environment. The requirement is an existing Fo ## Example Configuration +Create a `.env` file with: + ```env -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_BOT_USERNAME="myst-bot" -FORGEJO_PAT="fgp_xxxxxxxxxxxxxxxxxxxx" -GRANT_TOKEN_SECRET="your-secret-here" +# Same-host (Docker network or localhost): +FORGEJO_BASE_URL=http://forgejo:3000 +# Cross-host alternative: +# FORGEJO_BASE_URL=https://git.example.com +FORGEJO_PAT=forgejo_pat_xxxxxxxxxxxx ``` +When using the provided Docker Compose example, DATABASE_URL is injected automatically. For other deployment approaches (e.g., bare metal, Kubernetes), you must supply DATABASE_URL yourself. + ## Phase 1 Progress - [x] Project renamed from Embargo to Myst diff --git a/packages/cli/examples/docker-compose.example.yml b/packages/cli/examples/docker-compose.example.yml new file mode 100644 index 0000000..d63a52f --- /dev/null +++ b/packages/cli/examples/docker-compose.example.yml @@ -0,0 +1,42 @@ +# Docker Compose example for deploying Myst with PostgreSQL +# +# Usage: +# 1. Copy to docker-compose.yml: cp packages/cli/examples/docker-compose.example.yml docker-compose.yml +# 2. Edit .env with your Forgejo config +# 3. Run: docker compose up -d +# +# The DATABASE_URL is auto-handled by Docker Compose networking. + +services: + myst: + image: myst:latest + container_name: myst + restart: unless-stopped + ports: + - "3000:3000" + environment: + - DATABASE_URL=postgresql://myst:myst@db:5432/myst + env_file: + - .env + depends_on: + db: + condition: service_healthy + + db: + image: postgres:16-alpine + container_name: myst-db + restart: unless-stopped + environment: + - POSTGRES_USER=myst + - POSTGRES_PASSWORD=myst + - POSTGRES_DB=myst + volumes: + - myst-postgres:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U myst -d myst"] + interval: 5s + timeout: 5s + retries: 5 + +volumes: + myst-postgres: diff --git a/packages/cli/examples/myst.config.example.json b/packages/cli/examples/myst.config.example.json index 386c1c2..d534c5e 100644 --- a/packages/cli/examples/myst.config.example.json +++ b/packages/cli/examples/myst.config.example.json @@ -1,6 +1,3 @@ { - "adminUrl": "https://admin.example.com", - "forgejoBaseUrl": "https://git.example.com", - "forgejoBotUsername": "myst-bot", - "publicUrl": "https://share.example.com" + "forgejoBaseUrl": "http://forgejo:3000" } diff --git a/packages/cli/src/commands/config/init.ts b/packages/cli/src/commands/config/init.ts index 168b77d..16e05c4 100644 --- a/packages/cli/src/commands/config/init.ts +++ b/packages/cli/src/commands/config/init.ts @@ -4,11 +4,7 @@ import path from "node:path"; import * as c from "yoctocolors"; import * as p from "@clack/prompts"; -import { generateSecret } from "../../utils/crypto.js"; -import { - generateEnvFile, - SECRET_ENV_KEYS, -} from "../../utils/config.js"; +import { generateEnvFile, SECRET_ENV_KEYS } from "../../utils/config.js"; import { CommandConfig } from "../../cli-router.js"; function normalizeHttpUrl(value: string): string { @@ -20,7 +16,20 @@ function normalizeHttpUrl(value: string): string { throw new Error("URLs must use http:// or https://"); } - return hasProtocol ? trimmed : `https://${trimmed}`; + if (hasProtocol) return trimmed; + + // Infer scheme from the host shape: + // - localhost, IP literals, or single-label hosts (Docker service names + // like `forgejo`) default to http:// since they're typically internal. + // - Anything that looks like a public DNS name (contains a dot) defaults + // to https:// to preserve the existing behavior for `git.example.com`. + const host = trimmed.split("/")[0]?.split(":")[0] ?? ""; + const isInternalHost = + host === "localhost" || + /^\d{1,3}(\.\d{1,3}){3}$/.test(host) || + !host.includes("."); + + return `${isInternalHost ? "http" : "https"}://${trimmed}`; } function validateHttpUrlOrHost( @@ -42,23 +51,6 @@ function validateHttpUrlOrHost( return undefined; } -function validatePostgresUrl(value: string | undefined): string | undefined { - if (!value?.trim()) { - return "Database URL is required"; - } - - try { - const url = new URL(value); - if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") { - return "Database URL must start with postgres:// or postgresql://"; - } - } catch { - return "Database URL must be a valid Postgres connection string"; - } - - return undefined; -} - async function init(opts: { output?: string }) { p.intro(c.bold("myst config init")); p.note( @@ -72,7 +64,7 @@ async function init(opts: { output?: string }) { `- Repo permissions: ${c.cyan("https://forgejo.org/docs/latest/user/repo-permissions/")}`, `- Admin CLI: ${c.cyan("https://forgejo.org/docs/latest/admin/command-line/")}`, "", - `1. Create a dedicated Forgejo user such as ${c.bold("myst-bot")} and generate its PAT in Forgejo ${c.bold("Settings -> Applications")}.`, + `1. Generate a PAT in Forgejo ${c.bold("Settings -> Applications")}.`, `2. Generate a PAT with the appropriate scopes for your Forgejo setup.`, "", `Recommended PAT scopes:\n - ${c.bold("read:user")}\n - ${c.bold("read:repository")}\n - ${c.bold("read:organization")} (optional)`, @@ -118,7 +110,9 @@ async function init(opts: { output?: string }) { .map((line) => { if (!line.includes("=")) return line; const [key] = line.split("="); - return SECRET_ENV_KEYS.includes(key as typeof SECRET_ENV_KEYS[number]) + return SECRET_ENV_KEYS.includes( + key as (typeof SECRET_ENV_KEYS)[number], + ) ? `${key}=****` : line; }) @@ -135,52 +129,18 @@ async function init(opts: { output?: string }) { const answers = await p.group( { - publicUrl: () => - p.text({ - message: "Domain name or URL for the public viewer", - placeholder: "share.example.com", - validate: (v) => validateHttpUrlOrHost(v, "Public viewer URL"), - }), - adminUrl: () => - p.text({ - message: "Domain name or URL for the Myst admin UI", - placeholder: "admin.example.com", - validate: (v) => validateHttpUrlOrHost(v, "Private admin URL"), - }), forgejoBaseUrl: () => p.text({ - message: "Domain name or URL for your existing Forgejo instance?", - placeholder: "git.example.com", + message: "Forgejo API URL (how Myst reaches Forgejo, not your browser URL)?", + placeholder: "http://forgejo:3000", validate: (v) => validateHttpUrlOrHost(v, "Forgejo base URL"), }), - databaseUrl: () => - p.text({ - message: "What Postgres connection string should Myst use?", - placeholder: "postgresql://myst:password@db.example.com:5432/myst", - validate: validatePostgresUrl, - }), - forgejoBotUsername: () => - p.text({ - message: - "What dedicated Forgejo username should Myst use for API access?", - placeholder: "myst-bot", - validate: (v) => - v?.trim() ? undefined : "Dedicated Forgejo username is required", - }), forgejoPat: () => p.password({ - message: - "Paste the Forgejo personal access token for that dedicated Forgejo user", + message: "Paste the Forgejo personal access token", mask: "*", validate: (v) => (v?.trim() ? undefined : "Forgejo PAT is required"), }), - grantTokenSecret: () => - p.password({ - message: - "Paste a grant token secret, or press enter to generate one automatically", - mask: "*", - validate: () => undefined, - }), }, { onCancel: () => { @@ -195,20 +155,11 @@ async function init(opts: { output?: string }) { try { s.start("Generating config files"); - const publicUrl = normalizeHttpUrl(answers.publicUrl); - const adminUrl = normalizeHttpUrl(answers.adminUrl); const forgejoBaseUrl = normalizeHttpUrl(answers.forgejoBaseUrl); - const grantTokenSecret = - answers.grantTokenSecret?.trim() || generateSecret(); const envContent = generateEnvFile({ - adminUrl, - databaseUrl: answers.databaseUrl, forgejoBaseUrl, - forgejoBotUsername: answers.forgejoBotUsername, forgejoPat: answers.forgejoPat, - grantTokenSecret, - publicUrl, }); if (envExists) { @@ -232,12 +183,11 @@ async function init(opts: { output?: string }) { s.stop(c.yellow(`.env created at ${envPath}`)); p.note( [ - `${c.bold("Public viewer URL:")} ${c.cyan(publicUrl)}`, - `${c.bold("Admin URL:")} ${c.cyan(adminUrl)}`, - `${c.bold("Forgejo base URL:")} ${c.cyan(forgejoBaseUrl)}`, - `${c.bold("Myst bot username:")} ${c.cyan(answers.forgejoBotUsername)}`, + `${c.bold("Forgejo API URL:")} ${c.cyan(forgejoBaseUrl)}`, "", - `${c.bold("Admin URL reminder:")} protect this upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth.`, + `Myst will use this URL to call Forgejo's API.`, + `- Same host / Docker network: http://forgejo:3000 or http://localhost:3000`, + `- Cross-host deployment: https://git.example.com`, ].join("\n"), ); p.log.success( diff --git a/packages/cli/src/commands/verify.ts b/packages/cli/src/commands/verify.ts index d069c6b..27914e4 100644 --- a/packages/cli/src/commands/verify.ts +++ b/packages/cli/src/commands/verify.ts @@ -6,7 +6,6 @@ import * as p from "@clack/prompts"; import { ENV_MAPPING, parseEnvFile, REQUIRED_KEYS } from "../utils/config.js"; import { checkForgejoReachability, - checkForgejoApiAuthentication, checkRepoAccess, } from "../utils/forgejo-checks.js"; import { CommandConfig } from "../cli-router.js"; @@ -47,6 +46,12 @@ function getMissingKeys(config: Record): string[] { return missing; } +function formatCheck(result: CheckResult): string { + const icon = result.success ? c.green("✓") : c.red("✗"); + const msg = result.message ? ` ${result.message}` : ""; + return `${icon} ${result.name}${msg}`; +} + async function runDiagnosticMode( config: Record, missing: string[], @@ -73,11 +78,7 @@ async function runDiagnosticMode( const forgejoResults = await runForgejoChecks(config); const allResults = [...results, ...forgejoResults]; - const lines = allResults.map((r) => { - const icon = r.success ? c.green("✓") : c.red("✗"); - const msg = r.message ? ` ${r.message}` : ""; - return `${icon} ${r.name}${msg}`; - }); + const lines = allResults.map(formatCheck); p.note(lines.join("\n"), c.yellow("Results")); @@ -111,7 +112,7 @@ async function runVerifyMode( const firstFailure = forgejoResults.find((r) => !r.success); if (firstFailure) { s.stop(firstFailure.message); - p.cancel(`${c.red("✗")} ${firstFailure.name}: ${firstFailure.message}`); + p.cancel(formatCheck(firstFailure)); process.exitCode = 1; return; } @@ -125,14 +126,10 @@ async function runVerifyMode( s.stop("Verification complete"); - const [reachability, auth, repoAccess] = forgejoResults; + const [reachability, repoAccess] = forgejoResults; p.note( - [ - `${c.green("✓")} ${reachability.name}`, - `${c.green("✓")} ${auth.name}: ${auth.message}`, - `${c.green(repoAccess.success ? "✓" : "✗")} ${repoAccess.name}: ${repoAccess.message}`, - ].join("\n"), + [formatCheck(reachability), formatCheck(repoAccess)].join("\n"), c.yellow("Results"), ); @@ -142,9 +139,9 @@ async function runVerifyMode( async function runForgejoChecks( config: Record, ): Promise { - const { forgejoBaseUrl, forgejoPat, forgejoBotUsername } = config; + const { forgejoBaseUrl, forgejoPat } = config; - if (!forgejoBaseUrl || !forgejoPat || !forgejoBotUsername) { + if (!forgejoBaseUrl || !forgejoPat) { return []; } @@ -157,18 +154,7 @@ async function runForgejoChecks( return results; } - const auth = await checkForgejoApiAuthentication(forgejoBaseUrl, forgejoPat); - results.push(auth); - - if (!auth.success) { - return results; - } - - const repoAccess = await checkRepoAccess( - forgejoBaseUrl, - forgejoPat, - forgejoBotUsername, - ); + const repoAccess = await checkRepoAccess(forgejoBaseUrl, forgejoPat); results.push(repoAccess); return results; diff --git a/packages/cli/src/utils/config.ts b/packages/cli/src/utils/config.ts index 010f8da..b9a11ef 100644 --- a/packages/cli/src/utils/config.ts +++ b/packages/cli/src/utils/config.ts @@ -1,46 +1,20 @@ import fs from "node:fs"; export interface MystEnvironmentVariables { - publicUrl: string; - adminUrl: string; - databaseUrl: string; forgejoBaseUrl: string; - forgejoBotUsername: string; forgejoPat: string; - grantTokenSecret: string; } export const ENV_MAPPING = { - MYST_PUBLIC_URL: "publicUrl", - MYST_ADMIN_URL: "adminUrl", - DATABASE_URL: "databaseUrl", FORGEJO_BASE_URL: "forgejoBaseUrl", - FORGEJO_BOT_USERNAME: "forgejoBotUsername", FORGEJO_PAT: "forgejoPat", - GRANT_TOKEN_SECRET: "grantTokenSecret", } as const; -export const REQUIRED_KEYS = [ - "forgejoBaseUrl", - "forgejoBotUsername", - "forgejoPat", -] as const; +export const REQUIRED_KEYS = ["forgejoBaseUrl", "forgejoPat"] as const; -export const DATABASE_PROTOCOLS = ["postgres:", "postgresql:"] as const; +export const SECRET_KEYS = ["forgejoPat"] as const; -export const SECRET_KEYS = [ - "forgejoPat", - "grantTokenSecret", - "databaseUrl", - "adminUrl", -] as const; - -export const SECRET_ENV_KEYS = [ - "DATABASE_URL", - "FORGEJO_PAT", - "GRANT_TOKEN_SECRET", - "MYST_ADMIN_URL", -] as const; +export const SECRET_ENV_KEYS = ["FORGEJO_PAT"] as const; export function parseEnvFile( envPath: string, @@ -67,36 +41,13 @@ export function parseEnvFile( return config; } -export function validateDatabaseUrl(url: string | undefined): boolean { - if (!url) return false; - try { - const parsed = new URL(url); - return DATABASE_PROTOCOLS.includes( - parsed.protocol as "postgres:" | "postgresql:", - ); - } catch { - return false; - } -} - export function generateEnvFile(options: MystEnvironmentVariables): string { const lines = [ - `# Public URL used for share links.`, - `MYST_PUBLIC_URL=${options.publicUrl}`, - ``, - `# Private operator URL for the admin UI. Protect this upstream.`, - `MYST_ADMIN_URL=${options.adminUrl}`, - ``, - `# Myst's own Postgres database.`, - `DATABASE_URL=${options.databaseUrl}`, - ``, - `# Existing Forgejo instance and operator-created PAT for the dedicated Forgejo user.`, + `# Forgejo API endpoint that Myst calls.`, + `# Same-host / Docker: http://forgejo:3000 or http://localhost:3000`, + `# Cross-host: https://git.example.com`, `FORGEJO_BASE_URL=${options.forgejoBaseUrl}`, - `FORGEJO_BOT_USERNAME=${options.forgejoBotUsername}`, `FORGEJO_PAT=${options.forgejoPat}`, - ``, - `# Secret used to sign or derive grant tokens.`, - `GRANT_TOKEN_SECRET=${options.grantTokenSecret}`, ]; return lines.join("\n"); diff --git a/packages/cli/src/utils/forgejo-checks.ts b/packages/cli/src/utils/forgejo-checks.ts index 6f01257..95cca86 100644 --- a/packages/cli/src/utils/forgejo-checks.ts +++ b/packages/cli/src/utils/forgejo-checks.ts @@ -33,7 +33,10 @@ function getErrorMessage(error: unknown, context: string): string { if (error.message.includes("ECONNREFUSED")) { return `${context}: connection refused`; } - if (error.message.includes("ENOTFOUND") || error.message.includes("getaddrinfo")) { + if ( + error.message.includes("ENOTFOUND") || + error.message.includes("getaddrinfo") + ) { return `${context}: host not found`; } return `${context}: ${error.message}`; @@ -47,122 +50,73 @@ export async function checkForgejoReachability( try { const response = await fetchWithTimeout(baseUrl, { method: "GET" }); if (response.ok) { - return createCheckResult("Forgejo reachability", true, "connected"); + return createCheckResult("Forgejo", true, "is reachable"); } return createCheckResult( - "Forgejo reachability", + "Forgejo", false, `server returned ${response.status} ${response.statusText}`, ); } catch (error) { return createCheckResult( - "Forgejo reachability", + "Forgejo", false, getErrorMessage(error, "cannot reach server"), ); } } -export async function checkForgejoApiAuthentication( - baseUrl: string, - pat: string, -): Promise { - try { - const response = await fetchWithTimeout(`${baseUrl}/api/v1/user`, { - method: "GET", - headers: { - Authorization: `Bearer ${pat}`, - }, - }); - - if (response.status === 401) { - return createCheckResult( - "Forgejo API token", - false, - "token is invalid or expired", - ); - } - - if (response.status === 403) { - return createCheckResult( - "Forgejo API token", - false, - "token lacks sufficient permissions", - ); - } - - if (!response.ok) { - return createCheckResult( - "Forgejo API token", - false, - `server returned ${response.status}`, - ); - } - - const user = (await response.json()) as { login: string }; - return createCheckResult( - "Forgejo API token", - true, - `authenticated as ${user.login}`, - ); - } catch (error) { - return createCheckResult( - "Forgejo API token", - false, - getErrorMessage(error, "cannot connect to API"), - ); - } -} - export async function checkRepoAccess( baseUrl: string, pat: string, - username: string, ): Promise { try { - const response = await fetchWithTimeout( - `${baseUrl}/api/v1/users/${username}/repos?limit=1`, - { + const responses = await Promise.all([ + fetchWithTimeout(`${baseUrl}/api/v1/user`, { method: "GET", headers: { - Authorization: `Bearer ${pat}`, + Authorization: `token ${pat}`, }, - }, + }), + fetchWithTimeout(`${baseUrl}/api/v1/user/repos?limit=1`, { + method: "GET", + headers: { + Authorization: `token ${pat}`, + }, + }), + ]); + + const errorResponse = responses.find((res) => !res.ok); + if (errorResponse) { + const error = (await errorResponse.json()) as { + message: string; + url: string; + }; + return createCheckResult("Forgejo", false, error.message); + } + + const [userResponse, reposResponse] = responses; + const user = (await userResponse.json()) as { login: string }; + const totalRepos = parseInt( + reposResponse.headers.get("x-total-count") ?? "0", ); - if (response.status === 401 || response.status === 403) { + if (user) { return createCheckResult( - "Repo access", - false, - "token lacks permission to list repositories", - ); - } - - if (!response.ok) { - return createCheckResult( - "Repo access", - false, - `server returned ${response.status}`, - ); - } - - const repos = (await response.json()) as { name: string }[]; - if (repos.length > 0) { - return createCheckResult( - "Repo access", + "Forgejo", true, - `found ${repos.length} repository`, + `${user.login} has ${totalRepos} ${totalRepos === 1 ? "repository" : "repositories"}`, ); } return createCheckResult( - "Repo access", + "Forgejo", false, "no repositories found for user", ); } catch (error) { return createCheckResult( - "Repo access", + "Forgejo", false, getErrorMessage(error, "cannot list repositories"), );