@penpair/docker 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niklas Westman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @penpair/docker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The `penpair` command with Penpot in Docker on your computer. Design together. Build together.**
+
+[penpair](https://github.com/niklas-westman/penpair) connects your AI coding assistant to a [Penpot](https://penpot.app) design file. This package is the same command as [`@penpair/web`](https://www.npmjs.com/package/@penpair/web) plus the commands that run Penpot on your own machine: one private Penpot per project, started with one command, with generated secrets kept out of git, and `backup`, `backup verify` and `restore`.
+
+```bash
+npm i -D @penpair/docker
+npx penpair setup --docker
+```
+
+or, for a one-off run without installing: `npx @penpair/docker setup --docker`.
+
+It includes everything in [`@penpair/core`](https://www.npmjs.com/package/@penpair/core) (and everything `@penpair/web` has), so install it **instead of** `@penpair/web`, not beside it: both provide the command `penpair`.
+
+It needs Docker Desktop running and a 2 GB first download. The guide and the comparison of web and Docker are in the [repository](https://github.com/niklas-westman/penpair#web-or-docker).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from "@penpair/core";
+import { dockerProfile } from "./index.js";
+// The same `penpair` command as @penpair/core, with the commands that run Penpot in Docker added.
+process.exitCode = await runCli(process.argv.slice(2), { local: dockerProfile });

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { type LocalProfile } from "@penpair/core";
+export * from "@penpair/core";
+export { composeArgs, parseComposePs, readyUrl, waitForHttp } from "./lifecycle.js";
+export { firstFreePort, initDocker, isPortFree } from "./init.js";
+export { generateSecrets, readEnvValues, renderEnv, writeSecretFile } from "./secrets.js";
+export { renderCompose } from "./template.js";
+/** The Docker way of running Penpot: what the `penpair` command is started with. */
+export declare const dockerProfile: LocalProfile;

package/dist/index.js

@@ -0,0 +1,25 @@
+import { ConfigError } from "@penpair/core";
+import { initDocker } from "./init.js";
+import { backup, doctor, down, restore, status, up, verifyBackup } from "./lifecycle.js";
+// Everything the core has, so that a project with the Docker package imports from one place.
+export * from "@penpair/core";
+export { composeArgs, parseComposePs, readyUrl, waitForHttp } from "./lifecycle.js";
+export { firstFreePort, initDocker, isPortFree } from "./init.js";
+export { generateSecrets, readEnvValues, renderEnv, writeSecretFile } from "./secrets.js";
+export { renderCompose } from "./template.js";
+/** The Docker way of running Penpot: what the `penpair` command is started with. */
+export const dockerProfile = {
+    async preflight(runner) {
+        const version = await runner.run("docker", ["version", "--format", "{{.Server.Version}}"]);
+        if (version.code !== 0)
+            throw new ConfigError("Docker is not running. Start Docker Desktop, wait until it says it is running, then run the command again.");
+    },
+    init: initDocker,
+    up,
+    down,
+    status,
+    doctor,
+    backup,
+    verifyBackup,
+    restore,
+};

package/dist/init.d.ts

@@ -0,0 +1,8 @@
+import { type InitOptions, type InitResult } from "@penpair/core";
+export declare function isPortFree(port: number, host?: string): Promise<boolean>;
+export declare function firstFreePort(from: number, avoid?: number[], free?: (port: number) => Promise<boolean>): Promise<number>;
+/**
+ * Sets an instance up in a project: config (committed), then the generated compose file and secrets (in a git-ignored
+ * directory). Running it again rewrites the compose file from the config; existing secrets are never replaced.
+ */
+export declare function initDocker(root: string, options?: InitOptions): Promise<InitResult>;

package/dist/init.js

@@ -0,0 +1,62 @@
+import { createServer } from "node:net";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { configFileName, ConfigError, defaultInstanceName, ensureGitignoreEntry, ensureKeyFileIgnored, instancePaths, isExternal, loadConfig, testedPenpotVersion, validateConfig, } from "@penpair/core";
+import { generateSecrets, renderEnv, writeSecretFile } from "./secrets.js";
+import { renderCompose } from "./template.js";
+export async function isPortFree(port, host = "127.0.0.1") {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => server.close(() => resolve(true)));
+        server.listen(port, host);
+    });
+}
+export async function firstFreePort(from, avoid = [], free = isPortFree) {
+    for (let port = from; port < from + 200; port++)
+        if (!avoid.includes(port) && (await free(port)))
+            return port;
+    throw new Error(`no free port from ${from}`);
+}
+const ensureGitignore = (root, entry) => ensureGitignoreEntry(root, entry, { directory: true, comment: "penpair: generated compose file, secrets and backups" });
+/**
+ * Sets an instance up in a project: config (committed), then the generated compose file and secrets (in a git-ignored
+ * directory). Running it again rewrites the compose file from the config; existing secrets are never replaced.
+ */
+export async function initDocker(root, options = {}) {
+    let config;
+    let createdConfig = false;
+    try {
+        config = await loadConfig(root);
+    }
+    catch (error) {
+        if (!(error instanceof ConfigError) || !/No penpair\.config\.json/.test(error.message))
+            throw error;
+        const free = options.isFree ?? isPortFree;
+        const frontend = options.port ?? (await firstFreePort(9001, [], free));
+        const mail = options.mailPort ?? (await firstFreePort(1080, [frontend], free));
+        config = validateConfig({
+            instance: options.instance ?? defaultInstanceName(root),
+            penpotVersion: options.penpotVersion ?? testedPenpotVersion,
+            ports: { frontend, mail },
+            directory: options.directory ?? ".penpair",
+            ...(options.composeProject ? { composeProject: options.composeProject } : {}),
+        });
+        await writeFile(path.join(root, configFileName), `${JSON.stringify(config, null, 2)}\n`);
+        createdConfig = true;
+    }
+    if (isExternal(config))
+        throw new ConfigError("This project uses a Penpot that someone else runs; there is nothing for Docker to set up.");
+    const paths = instancePaths(root, config);
+    await mkdir(paths.directory, { recursive: true });
+    await writeFile(paths.compose, renderCompose(config));
+    const files = [paths.compose];
+    const createdSecrets = await writeSecretFile(paths.env, renderEnv(config, generateSecrets()));
+    files.push(paths.env);
+    let gitignoreAdded = false;
+    if (options.gitignore) {
+        const directoryAdded = await ensureGitignore(root, config.directory);
+        gitignoreAdded = (await ensureKeyFileIgnored(root)) || directoryAdded;
+    }
+    return { config, createdConfig, createdSecrets, files, gitignoreAdded };
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,46 @@
+import { type BackupManifest, type Check, type LocalContext, type DoctorCheck, type DoctorOptions, type InstanceConfig, type RestoreOptions, type ServiceState } from "@penpair/core";
+/** Kept under its old name inside this package. */
+type Context = LocalContext;
+/** `docker compose` arguments for this instance: its own project name, compose file and secrets. */
+export declare function composeArgs(c: Context, ...rest: string[]): string[];
+/** The frontend answers a few seconds before the backend does (502 until then); /readyz is 200 only when the backend is ready. */
+export declare const readyUrl: (config: InstanceConfig) => string;
+export declare function waitForHttp(c: Context, url: string, timeoutMs?: number, stepMs?: number): Promise<boolean>;
+export declare function up(c: Context): Promise<{
+    url: string;
+    ready: boolean;
+}>;
+/** Stops and removes the containers. Volumes are never removed: the design data stays. */
+export declare function down(c: Context): Promise<void>;
+export declare function parseComposePs(output: string): ServiceState[];
+export declare function status(c: Context): Promise<{
+    services: ServiceState[];
+    frontendReachable: boolean;
+    backendReady: boolean;
+    url: string;
+}>;
+/**
+ * A backup of the whole instance: a Postgres dump and a tarball of the asset volume, with checksums and the counts
+ * that `backup verify` later checks a restore against. It holds account data (password hashes): never commit it.
+ */
+export declare function backup(c: Context, label?: string): Promise<{
+    directory: string;
+    manifest: BackupManifest;
+}>;
+/** Proves a backup can be restored without touching the instance: restores the dump into a throwaway Postgres and compares. */
+export declare function verifyBackup(c: Context, directory: string): Promise<{
+    ok: boolean;
+    checks: Check[];
+}>;
+/**
+ * Replaces the instance's database and assets with a backup. A backup of the current data is taken first unless told
+ * not to, the checksums are checked before anything is touched, and the counts are compared afterwards.
+ */
+export declare function restore(c: Context, directory: string, options: RestoreOptions): Promise<{
+    ok: boolean;
+    checks: Check[];
+    safetyBackup?: string;
+}>;
+/** What is up, what is not, and what to do about it. */
+export declare function doctor(c: Context, options?: DoctorOptions): Promise<DoctorCheck[]>;
+export {};

package/dist/lifecycle.js

@@ -0,0 +1,272 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { composeProjectOf, endpointIsInstance, frontendUrl, instancePaths, LifecycleError, } from "@penpair/core";
+import { readEnvValues } from "./secrets.js";
+const defaultSleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const sleepOf = (c) => c.sleep ?? defaultSleep;
+const say = (c, message) => c.log?.(message);
+/** `docker compose` arguments for this instance: its own project name, compose file and secrets. */
+export function composeArgs(c, ...rest) {
+    const paths = instancePaths(c.root, c.config);
+    return ["compose", "-p", composeProjectOf(c.config), "-f", paths.compose, "--env-file", paths.env, ...rest];
+}
+async function docker(c, args, what) {
+    const result = await c.runner.run("docker", args);
+    if (result.code !== 0)
+        throw new LifecycleError(`${what} failed: ${result.stderr.trim().split("\n").slice(-3).join(" ") || `exit ${result.code}`}`);
+    return result.stdout;
+}
+/** The frontend answers a few seconds before the backend does (502 until then); /readyz is 200 only when the backend is ready. */
+export const readyUrl = (config) => `${frontendUrl(config)}/readyz`;
+export async function waitForHttp(c, url, timeoutMs = 240_000, stepMs = 3_000) {
+    const doFetch = c.fetch ?? fetch;
+    for (let waited = 0; waited <= timeoutMs; waited += stepMs) {
+        try {
+            const response = await doFetch(url, { redirect: "manual" });
+            if (response.status < 500)
+                return true;
+        }
+        catch {
+            // not up yet
+        }
+        await sleepOf(c)(stepMs);
+    }
+    return false;
+}
+export async function up(c) {
+    say(c, "starting the containers");
+    await docker(c, composeArgs(c, "up", "-d"), "docker compose up");
+    say(c, "waiting for Penpot to answer (the first start can take a few minutes)");
+    return { url: frontendUrl(c.config), ready: await waitForHttp(c, readyUrl(c.config)) };
+}
+/** Stops and removes the containers. Volumes are never removed: the design data stays. */
+export async function down(c) {
+    await docker(c, composeArgs(c, "down"), "docker compose down");
+}
+export function parseComposePs(output) {
+    const rows = [];
+    const text = output.trim();
+    if (text.startsWith("["))
+        rows.push(...JSON.parse(text));
+    else
+        for (const line of text.split("\n").filter(Boolean))
+            rows.push(JSON.parse(line));
+    return rows.map((row) => {
+        const r = row;
+        return { service: r.Service ?? r.Name ?? "?", state: r.State ?? "?", health: r.Health ?? "" };
+    });
+}
+export async function status(c) {
+    const output = await docker(c, composeArgs(c, "ps", "--all", "--format", "json"), "docker compose ps");
+    const services = output.trim() ? parseComposePs(output) : [];
+    const url = frontendUrl(c.config);
+    const answers = async (target, ok) => {
+        try {
+            return ok((await (c.fetch ?? fetch)(target, { redirect: "manual" })).status);
+        }
+        catch {
+            return false;
+        }
+    };
+    return { services, frontendReachable: await answers(url, (code) => code < 500), backendReady: await answers(readyUrl(c.config), (code) => code === 200), url };
+}
+async function containerOf(c, service) {
+    const id = (await docker(c, composeArgs(c, "ps", "-q", service), `docker compose ps ${service}`)).trim().split("\n")[0];
+    if (!id)
+        throw new LifecycleError(`The ${service} container is not running. Run \`penpair up\` first.`);
+    return id;
+}
+const countsSql = `select json_build_object('files',(select count(*) from file where deleted_at is null),'profiles',(select count(*) from profile),'teams',(select count(*) from team),'storageObjects',(select count(*) from storage_object),'fileRevisions',(select coalesce(json_agg(json_build_object('id',id,'name',name,'revn',revn) order by name,id),'[]'::json) from file where deleted_at is null))`;
+async function readCounts(c, container) {
+    const out = await docker(c, ["exec", container, "psql", "-U", "penpot", "-d", "penpot", "-tAc", countsSql], "reading the database counts");
+    return JSON.parse(out.trim());
+}
+async function sha256File(file) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(file))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+/**
+ * A backup of the whole instance: a Postgres dump and a tarball of the asset volume, with checksums and the counts
+ * that `backup verify` later checks a restore against. It holds account data (password hashes): never commit it.
+ */
+export async function backup(c, label) {
+    const paths = instancePaths(c.root, c.config);
+    const stamp = (c.now?.() ?? new Date()).toISOString().replace(/[:.]/g, "-");
+    const directory = path.join(paths.backups, label ? `${stamp}-${label}` : stamp);
+    await mkdir(directory, { recursive: true });
+    const postgres = await containerOf(c, "penpot-postgres");
+    const backend = await containerOf(c, "penpot-backend");
+    say(c, "dumping the database");
+    const dump = await c.runner.run("docker", ["exec", postgres, "pg_dump", "-U", "penpot", "-d", "penpot", "-Fc"], { outFile: path.join(directory, "db.dump") });
+    if (dump.code !== 0)
+        throw new LifecycleError(`pg_dump failed: ${dump.stderr.trim().slice(-200)}`);
+    say(c, "archiving the assets");
+    const assets = await c.runner.run("docker", ["exec", backend, "tar", "czf", "-", "-C", "/opt/data/assets", "."], { outFile: path.join(directory, "assets.tgz") });
+    if (assets.code !== 0)
+        throw new LifecycleError(`archiving the assets failed: ${assets.stderr.trim().slice(-200)}`);
+    const entry = async (name) => ({ name, sha256: await sha256File(path.join(directory, name)), bytes: (await stat(path.join(directory, name))).size });
+    const manifest = {
+        instance: c.config.instance,
+        penpotVersion: c.config.penpotVersion,
+        createdAt: (c.now?.() ?? new Date()).toISOString(),
+        ...(label ? { label } : {}),
+        files: { db: await entry("db.dump"), assets: await entry("assets.tgz") },
+        counts: await readCounts(c, postgres),
+        note: "Contains account data (password hashes). Never commit it. Keep the instance's .env with it.",
+    };
+    await writeFile(path.join(directory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    return { directory, manifest };
+}
+async function loadManifest(directory) {
+    try {
+        return JSON.parse(await readFile(path.join(directory, "manifest.json"), "utf8"));
+    }
+    catch {
+        throw new LifecycleError(`${directory} is not a penpair backup (no manifest.json)`);
+    }
+}
+async function checksumChecks(directory, manifest) {
+    const checks = [];
+    for (const key of ["db", "assets"]) {
+        const wanted = manifest.files[key];
+        let actual = "missing";
+        try {
+            actual = await sha256File(path.join(directory, wanted.name));
+        }
+        catch {
+            // reported below
+        }
+        checks.push({ check: `${wanted.name} checksum`, ok: actual === wanted.sha256, detail: actual === wanted.sha256 ? "matches the manifest" : `expected ${wanted.sha256.slice(0, 12)}, found ${actual.slice(0, 12)}` });
+    }
+    return checks;
+}
+const compareCounts = (wanted, found) => [
+    ...["files", "profiles", "teams", "storageObjects"].map((key) => ({ check: `restored ${key}`, ok: wanted[key] === found[key], detail: `${found[key]} (backup says ${wanted[key]})` })),
+    { check: "file revisions", ok: JSON.stringify(wanted.fileRevisions) === JSON.stringify(found.fileRevisions), detail: `${found.fileRevisions.length} files, ids, names and revisions ${JSON.stringify(wanted.fileRevisions) === JSON.stringify(found.fileRevisions) ? "match" : "differ"}` },
+];
+/** Proves a backup can be restored without touching the instance: restores the dump into a throwaway Postgres and compares. */
+export async function verifyBackup(c, directory) {
+    const manifest = await loadManifest(directory);
+    const checks = await checksumChecks(directory, manifest);
+    const name = `penpair-verify-${Math.random().toString(36).slice(2, 8)}`;
+    say(c, "starting a throwaway Postgres");
+    await docker(c, ["run", "-d", "--name", name, "-e", "POSTGRES_USER=penpot", "-e", "POSTGRES_PASSWORD=verify", "-e", "POSTGRES_DB=penpot", "-v", `${path.resolve(directory)}:/backup:ro`, "postgres:15"], "starting the throwaway Postgres");
+    try {
+        let ready = false;
+        for (let i = 0; i < 40 && !ready; i++) {
+            ready = (await c.runner.run("docker", ["exec", name, "pg_isready", "-U", "penpot", "-d", "penpot"])).code === 0;
+            if (!ready)
+                await sleepOf(c)(1_000);
+        }
+        if (!ready)
+            throw new LifecycleError("the throwaway Postgres did not become ready");
+        say(c, "restoring the dump");
+        await c.runner.run("docker", ["exec", name, "pg_restore", "-U", "penpot", "-d", "penpot", "--no-owner", "/backup/db.dump"]);
+        checks.push(...compareCounts(manifest.counts, await readCounts(c, name)));
+        const listing = await c.runner.run("tar", ["tzf", path.join(directory, manifest.files.assets.name)]);
+        const entries = listing.stdout.split("\n").filter((line) => line && !line.endsWith("/")).length;
+        checks.push({ check: "asset files", ok: entries === manifest.counts.storageObjects, detail: `${entries} files in the tarball, ${manifest.counts.storageObjects} storage objects` });
+    }
+    finally {
+        await c.runner.run("docker", ["rm", "-f", name]);
+    }
+    return { ok: checks.every((check) => check.ok), checks };
+}
+/**
+ * Replaces the instance's database and assets with a backup. A backup of the current data is taken first unless told
+ * not to, the checksums are checked before anything is touched, and the counts are compared afterwards.
+ */
+export async function restore(c, directory, options) {
+    if (!options.yes)
+        throw new LifecycleError("Restoring replaces this instance's data. Run again with --yes to confirm.");
+    const manifest = await loadManifest(directory);
+    const checks = await checksumChecks(directory, manifest);
+    if (!checks.every((check) => check.ok))
+        return { ok: false, checks };
+    let safetyBackup;
+    if (!options.skipSafetyBackup) {
+        try {
+            say(c, "taking a safety backup of the current data first");
+            safetyBackup = (await backup(c, "pre-restore")).directory;
+        }
+        catch (error) {
+            if (!(error instanceof LifecycleError) || !/not running/.test(error.message))
+                throw error;
+            say(c, "the instance is not running, so there is no current data to back up");
+        }
+    }
+    say(c, "stopping the application containers");
+    await docker(c, composeArgs(c, "stop", "penpot-frontend", "penpot-backend", "penpot-admin-console", "penpot-exporter", "penpot-mcp"), "stopping the application containers");
+    await docker(c, composeArgs(c, "up", "-d", "penpot-postgres", "penpot-valkey"), "starting the database");
+    const postgres = await containerOf(c, "penpot-postgres");
+    for (let i = 0; i < 60; i++) {
+        if ((await c.runner.run("docker", ["exec", postgres, "pg_isready", "-U", "penpot", "-d", "penpot"])).code === 0)
+            break;
+        await sleepOf(c)(1_000);
+    }
+    say(c, "replacing the database");
+    await docker(c, ["exec", postgres, "psql", "-U", "penpot", "-d", "postgres", "-c", "drop database penpot with (force)"], "dropping the database");
+    await docker(c, ["exec", postgres, "psql", "-U", "penpot", "-d", "postgres", "-c", "create database penpot"], "creating the database");
+    const loaded = await c.runner.run("docker", ["exec", "-i", postgres, "pg_restore", "-U", "penpot", "-d", "penpot", "--no-owner"], { inFile: path.join(directory, manifest.files.db.name) });
+    if (loaded.code !== 0)
+        throw new LifecycleError(`pg_restore failed: ${loaded.stderr.trim().slice(-200)}`);
+    say(c, "replacing the assets");
+    const volume = `${composeProjectOf(c.config)}_penpot_assets`;
+    const assets = await c.runner.run("docker", ["run", "--rm", "-i", "-v", `${volume}:/data`, "--entrypoint", "sh", `penpotapp/backend:${c.config.penpotVersion}`, "-c", "find /data -mindepth 1 -delete && tar xzf - -C /data"], { inFile: path.join(directory, manifest.files.assets.name) });
+    if (assets.code !== 0)
+        throw new LifecycleError(`restoring the assets failed: ${assets.stderr.trim().slice(-200)}`);
+    say(c, "starting everything again");
+    await up(c);
+    checks.push(...compareCounts(manifest.counts, await readCounts(c, await containerOf(c, "penpot-postgres"))));
+    return { ok: checks.every((check) => check.ok), checks, ...(safetyBackup ? { safetyBackup } : {}) };
+}
+/** What is up, what is not, and what to do about it. */
+export async function doctor(c, options = {}) {
+    const out = [];
+    const add = (check, ok, detail, remedy) => void out.push({ check, ok, detail, ...(remedy && !ok ? { remedy } : {}) });
+    const version = await c.runner.run("docker", ["version", "--format", "{{.Server.Version}}"]);
+    add("docker", version.code === 0, version.code === 0 ? `engine ${version.stdout.trim()}` : "not answering", "Start Docker Desktop (or the Docker daemon).");
+    if (version.code !== 0)
+        return out;
+    const paths = instancePaths(c.root, c.config);
+    try {
+        const mode = (await stat(paths.env)).mode & 0o777;
+        const values = await readEnvValues(paths.env);
+        add("secrets file", mode === 0o600 && Boolean(values.PENPOT_SECRET_KEY) && Boolean(values.PENPOT_DATABASE_PASSWORD), `permissions ${mode.toString(8)}, keys ${values.PENPOT_SECRET_KEY && values.PENPOT_DATABASE_PASSWORD ? "present" : "missing"}`, "Run `penpair init` to create it, and `chmod 600` the file.");
+    }
+    catch {
+        add("secrets file", false, "missing", "Run `penpair init`.");
+    }
+    let state;
+    try {
+        state = await status(c);
+    }
+    catch (error) {
+        add("containers", false, String(error.message), "Run `penpair up`.");
+    }
+    if (state) {
+        const running = state.services.filter((s) => s.state === "running").map((s) => s.service);
+        const needed = ["penpot-frontend", "penpot-backend", "penpot-postgres", "penpot-mcp"];
+        const missing = needed.filter((service) => !running.includes(service));
+        add("containers", missing.length === 0, missing.length === 0 ? `${running.length} running` : `not running: ${missing.join(", ")}`, "Run `penpair up`.");
+        add("frontend", state.frontendReachable, state.frontendReachable ? state.url : `${state.url} does not answer`, "Run `penpair up` and wait for Penpot to start.");
+        add("backend", state.backendReady, state.backendReady ? "ready" : "not ready yet (the proxy answers, the backend does not)", "Wait a few seconds after `penpair up`; if it stays like this, read the backend log with `docker compose logs penpot-backend`.");
+    }
+    if (options.mcp && !endpointIsInstance(options.mcp.origin, c.config)) {
+        add("editor and plugin", false, `the MCP endpoint points at ${options.mcp.origin}, which is not this instance (${frontendUrl(c.config)})`, "Put this instance's MCP URL (Account, Integrations, MCP Server) in this project's .env.local as PENPAIR_MCP_URL.");
+    }
+    else if (options.mcp) {
+        try {
+            const { file } = await options.mcp.connect();
+            add("editor and plugin", true, `connected to file "${file}"`);
+        }
+        catch (error) {
+            add("editor and plugin", false, String(error.message).split("\n")[0] ?? "not connected", "Open a file in Penpot, choose File, MCP Server, Connect, and keep the tab visible.");
+        }
+    }
+    return out;
+}

package/dist/secrets.d.ts

@@ -0,0 +1,11 @@
+import type { InstanceConfig } from "@penpair/core";
+export interface Secrets {
+    secretKey: string;
+    databasePassword: string;
+}
+/** A 512-bit master key for Penpot and a database password. Generated once; changing the password later breaks an existing database volume. */
+export declare function generateSecrets(): Secrets;
+export declare function renderEnv(config: InstanceConfig, secrets: Secrets): string;
+/** Writes a file readable by its owner only. Refuses to overwrite unless told to. */
+export declare function writeSecretFile(file: string, content: string, overwrite?: boolean): Promise<boolean>;
+export declare function readEnvValues(file: string): Promise<Record<string, string>>;

package/dist/secrets.js

@@ -0,0 +1,38 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+/** A 512-bit master key for Penpot and a database password. Generated once; changing the password later breaks an existing database volume. */
+export function generateSecrets() {
+    return { secretKey: randomBytes(64).toString("base64url"), databasePassword: randomBytes(24).toString("base64url") };
+}
+export function renderEnv(config, secrets) {
+    return `# Generated by penpair. Secrets: never commit, never print. Keep this file with the backups; the database password
+# must stay the same for as long as the database volume exists.
+PENPOT_VERSION=${config.penpotVersion}
+PENPOT_SECRET_KEY=${secrets.secretKey}
+PENPOT_DATABASE_PASSWORD=${secrets.databasePassword}
+`;
+}
+/** Writes a file readable by its owner only. Refuses to overwrite unless told to. */
+export async function writeSecretFile(file, content, overwrite = false) {
+    await mkdir(path.dirname(file), { recursive: true });
+    try {
+        await writeFile(file, content, { mode: 0o600, flag: overwrite ? "w" : "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    await chmod(file, 0o600);
+    return true;
+}
+export async function readEnvValues(file) {
+    const out = {};
+    for (const line of (await readFile(file, "utf8")).split(/\r?\n/)) {
+        const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(line.trim());
+        if (match)
+            out[match[1]] = match[2];
+    }
+    return out;
+}

package/dist/template.d.ts

@@ -0,0 +1,8 @@
+import type { InstanceConfig } from "@penpair/core";
+/**
+ * The compose file for one instance. It follows the official Penpot compose file; the local changes are the defaults
+ * worth keeping: a pinned version, ports bound to 127.0.0.1, telemetry off, secrets only from `.env`, local mail capture,
+ * the MCP server on. Container ports of the database, cache, admin console, exporter and MCP are not published; the
+ * MCP is reached through the frontend at /mcp/stream.
+ */
+export declare function renderCompose(config: InstanceConfig): string;

package/dist/template.js

@@ -0,0 +1,158 @@
+/**
+ * The compose file for one instance. It follows the official Penpot compose file; the local changes are the defaults
+ * worth keeping: a pinned version, ports bound to 127.0.0.1, telemetry off, secrets only from `.env`, local mail capture,
+ * the MCP server on. Container ports of the database, cache, admin console, exporter and MCP are not published; the
+ * MCP is reached through the frontend at /mcp/stream.
+ */
+export function renderCompose(config) {
+    const { frontend, mail } = config.ports;
+    return `# Generated by penpair. Edit penpair.config.json and run \`penpair init\` again instead of editing this file.
+x-flags: &penpot-flags
+  PENPOT_FLAGS: disable-email-verification enable-smtp enable-prepl-server disable-secure-session-cookies enable-mcp enable-admin-console
+
+x-uri: &penpot-public-uri
+  PENPOT_PUBLIC_URI: http://localhost:${frontend}
+
+x-body-size: &penpot-http-body-size
+  PENPOT_HTTP_SERVER_MAX_BODY_SIZE: 367001600
+  PENPOT_HTTP_SERVER_MAX_MULTIPART_BODY_SIZE: 367001600
+
+x-secret-key: &penpot-secret-key
+  PENPOT_SECRET_KEY: \${PENPOT_SECRET_KEY:?Set PENPOT_SECRET_KEY in .env}
+
+x-database: &penpot-database
+  PENPOT_DATABASE_URI: postgresql://penpot-postgres/penpot
+  PENPOT_DATABASE_USERNAME: penpot
+  PENPOT_DATABASE_PASSWORD: \${PENPOT_DATABASE_PASSWORD:?Set PENPOT_DATABASE_PASSWORD in .env}
+
+networks:
+  penpot:
+
+volumes:
+  penpot_postgres_v15:
+  penpot_assets:
+
+services:
+  penpot-frontend:
+    image: "penpotapp/frontend:\${PENPOT_VERSION:-${config.penpotVersion}}"
+    restart: always
+    ports:
+      - "127.0.0.1:${frontend}:8080"
+    volumes:
+      - penpot_assets:/opt/data/assets
+    depends_on:
+      - penpot-backend
+      - penpot-admin-console
+      - penpot-mcp
+      - penpot-exporter
+    networks:
+      - penpot
+    environment:
+      << : [*penpot-flags, *penpot-http-body-size, *penpot-public-uri]
+      PENPOT_ADMIN_CONSOLE_URI: http://penpot-admin-console:3000
+
+  penpot-backend:
+    image: "penpotapp/backend:\${PENPOT_VERSION:-${config.penpotVersion}}"
+    restart: always
+    volumes:
+      - penpot_assets:/opt/data/assets
+    depends_on:
+      penpot-postgres:
+        condition: service_healthy
+      penpot-valkey:
+        condition: service_healthy
+    networks:
+      - penpot
+    environment:
+      << : [*penpot-flags, *penpot-public-uri, *penpot-http-body-size, *penpot-secret-key, *penpot-database]
+      PENPOT_ADMIN_CONSOLE_URI: http://penpot-admin-console:3000
+      PENPOT_REDIS_URI: redis://penpot-valkey/0
+      PENPOT_OBJECTS_STORAGE_BACKEND: fs
+      PENPOT_OBJECTS_STORAGE_FS_DIRECTORY: /opt/data/assets
+      PENPOT_TELEMETRY_ENABLED: "false"
+      PENPOT_TELEMETRY_REFERER: compose
+      PENPOT_SMTP_DEFAULT_FROM: no-reply@example.com
+      PENPOT_SMTP_DEFAULT_REPLY_TO: no-reply@example.com
+      PENPOT_SMTP_HOST: penpot-mailcatch
+      PENPOT_SMTP_PORT: 1025
+      PENPOT_SMTP_USERNAME:
+      PENPOT_SMTP_PASSWORD:
+      PENPOT_SMTP_TLS: "false"
+      PENPOT_SMTP_SSL: "false"
+
+  penpot-admin-console:
+    image: "penpotapp/admin-console:\${PENPOT_VERSION:-${config.penpotVersion}}"
+    restart: always
+    depends_on:
+      penpot-postgres:
+        condition: service_healthy
+    networks:
+      - penpot
+    environment:
+      << : [*penpot-public-uri, *penpot-secret-key, *penpot-database]
+      PENPOT_INTERNAL_URI: http://penpot-frontend:8080
+
+  penpot-mcp:
+    image: "penpotapp/mcp:\${PENPOT_VERSION:-${config.penpotVersion}}"
+    restart: always
+    networks:
+      - penpot
+
+  penpot-exporter:
+    image: "penpotapp/exporter:\${PENPOT_VERSION:-${config.penpotVersion}}"
+    restart: always
+    depends_on:
+      penpot-valkey:
+        condition: service_healthy
+    networks:
+      - penpot
+    environment:
+      << : [*penpot-flags, *penpot-secret-key, *penpot-public-uri]
+      PENPOT_INTERNAL_URI: http://penpot-frontend:8080
+      PENPOT_REDIS_URI: redis://penpot-valkey/0
+
+  penpot-postgres:
+    image: "postgres:15"
+    restart: always
+    stop_signal: SIGINT
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U penpot"]
+      interval: 2s
+      timeout: 10s
+      retries: 5
+      start_period: 2s
+    volumes:
+      - penpot_postgres_v15:/var/lib/postgresql/data
+    networks:
+      - penpot
+    environment:
+      - POSTGRES_INITDB_ARGS=--data-checksums
+      - POSTGRES_DB=penpot
+      - POSTGRES_USER=penpot
+      - POSTGRES_PASSWORD=\${PENPOT_DATABASE_PASSWORD:?Set PENPOT_DATABASE_PASSWORD in .env}
+
+  penpot-valkey:
+    image: valkey/valkey:8.1
+    restart: always
+    healthcheck:
+      test: ["CMD-SHELL", "valkey-cli ping | grep PONG"]
+      interval: 1s
+      timeout: 3s
+      retries: 5
+      start_period: 3s
+    networks:
+      - penpot
+    environment:
+      - VALKEY_EXTRA_FLAGS=--maxmemory 128mb --maxmemory-policy volatile-lfu
+
+  penpot-mailcatch:
+    image: sj26/mailcatcher:latest
+    restart: always
+    expose:
+      - '1025'
+    ports:
+      - "127.0.0.1:${mail}:1080"
+    networks:
+      - penpot
+`;
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@penpair/docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Everything in @penpair/core, plus running Penpot in Docker on your computer: one instance per project, generated secrets, up and down, backup, verify and restore.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niklas-westman/penpair.git",
+    "directory": "packages/docker"
+  },
+  "homepage": "https://github.com/niklas-westman/penpair#readme",
+  "bugs": {
+    "url": "https://github.com/niklas-westman/penpair/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "penpot",
+    "docker",
+    "design-systems",
+    "mcp",
+    "ai-agents",
+    "developer-tools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@penpair/core": "0.1.1"
+  },
+  "bin": {
+    "penpair": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }