Compare commits

...
Sign in to create a new pull request.

6 commits

Author SHA1 Message Date
ZTatman
69ad95a7b2 fix(cli): unlink .env.temp before writing to file in case it was already
created
2026-04-18 13:30:07 -04:00
ZTatman
cd216cd660 refactor(cli): simplify base url validation/normalization, update readme
and docs to reflect possible deployment configurations
2026-04-17 12:40:58 -04:00
ZTatman
b87c4554fb refactor(cli): specify that forgejo base url should point to internal
forgejo address in container
2026-04-16 13:02:01 -04:00
ZTatman
4ceb1ff223 chore(cli): fix some formatting 2026-04-15 22:20:07 -04:00
ZTatman
bbf3bfc48a refactor(cli): user proper api endpoints to get forgejo username and
total repo count when verifying
2026-04-15 22:09:02 -04:00
ZTatman
29cd2f046d simplify: reduce CLI config to just Forgejo URL and PAT
Removes unnecessary configuration that operators dont need to provide:
- Removed MYST_PUBLIC_URL, MYST_ADMIN_URL (users buy their own domains)
- Removed FORGEJO_BOT_USERNAME (API returns username)
- Removed DATABASE_URL (Docker Compose handles it)
- Removed GRANT_TOKEN_SECRET (auto-generated on startup)

Simplifies init to just 2 prompts:
- Forgejo base URL
- Forgejo PAT

Adds Docker Compose example with PostgreSQL.

Verify now shows:
- FORGEJO_BASE_URL configured
- FORGEJO_PAT configured
- Forgejo is reachable
- Forgejo User <username> has <n> repositories
2026-04-15 20:53:58 -04:00
7 changed files with 151 additions and 279 deletions

View file

@ -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 — Docker: `http://forgejo:3000`, bare metal: `http://localhost:3000`, 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,20 @@ 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"
# Docker (same Compose network):
FORGEJO_BASE_URL=http://forgejo:3000
# Bare metal / non-container:
# FORGEJO_BASE_URL=http://localhost:3000
# Cross-host:
# 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

View file

@ -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:

View file

@ -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"
}

View file

@ -4,56 +4,32 @@ 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 {
const trimmed = value.trim();
const hasProtocol = /^[a-z]+:\/\//i.test(trimmed);
const isNotHttp = !/^https?:\/\//i.test(trimmed);
if (hasProtocol && isNotHttp) {
throw new Error("URLs must use http:// or https://");
}
return hasProtocol ? trimmed : `https://${trimmed}`;
}
function validateHttpUrlOrHost(
value: string | undefined,
label: string,
): string | undefined {
if (!value?.trim()) return `${label} is required`;
const trimmed = value?.trim();
if (!trimmed) return `${label} is required`;
try {
const normalized = normalizeHttpUrl(value);
const url = new URL(normalized);
if (!url.hostname) {
return `${label} must include a domain or hostname`;
}
} catch {
return `${label} must be a valid URL or hostname`;
const hasProtocol = /^[a-z]+:\/\//i.test(trimmed);
const isHttp = /^https?:\/\//i.test(trimmed);
if (hasProtocol && !isHttp) {
return `${label} must use http:// or https://`;
}
return undefined;
}
function validatePostgresUrl(value: string | undefined): string | undefined {
if (!value?.trim()) {
return "Database URL is required";
if (!hasProtocol) {
return `${label} must include a scheme — e.g. http://forgejo:3000 or https://git.example.com`;
}
try {
const url = new URL(value);
if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
return "Database URL must start with postgres:// or postgresql://";
}
const url = new URL(trimmed);
if (!url.hostname) return `${label} must include a domain or hostname`;
} catch {
return "Database URL must be a valid Postgres connection string";
return `${label} must be a valid URL`;
}
return undefined;
@ -72,7 +48,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 +94,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 +113,19 @@ 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",
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",
"Forgejo API URL (how Myst reaches Forgejo, not your browser URL)?",
placeholder: "http://forgejo:3000",
validate: (v) => validateHttpUrlOrHost(v, "Forgejo base URL"),
}),
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,24 +140,16 @@ 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 forgejoBaseUrl = answers.forgejoBaseUrl.trim();
const envContent = generateEnvFile({
adminUrl,
databaseUrl: answers.databaseUrl,
forgejoBaseUrl,
forgejoBotUsername: answers.forgejoBotUsername,
forgejoPat: answers.forgejoPat,
grantTokenSecret,
publicUrl,
});
if (envExists) {
const tempPath = envPath + ".tmp";
await fs.unlink(tempPath).catch(() => {});
await fs.writeFile(tempPath, envContent, {
encoding: "utf8",
flag: "wx",
@ -232,12 +169,12 @@ 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.`,
`- 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(

View file

@ -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, string>): 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<string, string>,
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<string, string>,
): Promise<CheckResult[]> {
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;

View file

@ -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,14 @@ 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.`,
`# Docker (same Compose network): http://forgejo:3000`,
`# Bare metal / non-container: 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");

View file

@ -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<CheckResult> {
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<CheckResult> {
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"),
);