@dokebi/cli 0.4.2 → 0.4.27

package/dist/deploy-templates.js

@@ -0,0 +1,379 @@
+// The texts `dokebi deploy init` and `dokebi deploy proxy` write (D-0184): one instance of an
+// app on a Linux server, laid out so staging and production on the same server never share a
+// port, unit, user, settings, data, log, backup or database name.
+export function layout(app, instance, port) {
+    return {
+        app,
+        instance,
+        port,
+        unit: `${app}-${instance}`,
+        settings: `/etc/${app}/${instance}/dokebi.yaml`,
+        secrets: `/etc/${app}/${instance}/secrets.yaml`,
+        code: `/srv/${app}/${instance}`,
+        data: `/var/lib/${app}/${instance}`,
+        logs: `/var/log/${app}/${instance}`,
+        backups: `/var/backups/${app}/${instance}`,
+        database: `${app}_${instance}`.replaceAll('-', '_'),
+    };
+}
+export function systemdUnit(at) {
+    return `[Unit]
+Description=${at.app} (${at.instance})
+Documentation=file://${at.code}/current/DEPLOY.md
+After=network-online.target
+Wants=network-online.target
+# Start after the services this app connects to, e.g.:
+# After=network-online.target postgresql.service redis-server.service
+
+[Service]
+Type=exec
+User=${at.unit}
+Group=${at.unit}
+WorkingDirectory=${at.code}/current
+Environment=NODE_ENV=production
+Environment=DOKEBI_CONFIG=${at.settings}
+Environment=DOKEBI_SECRETS=${at.secrets}
+# The node of the server (command -v node); Node.js 24 or later.
+ExecStart=/usr/bin/node src/main.ts
+# The app drains on SIGTERM; keep TimeoutStopSec above its drain and cleanup budget.
+KillSignal=SIGTERM
+TimeoutStopSec=60
+Restart=on-failure
+RestartSec=5
+# Writable: ${at.data} (StateDirectory: storage and other app files) and
+# ${at.logs} (LogsDirectory: file log targets). Records on stdout go to the journal:
+# journalctl -u ${at.unit}
+StateDirectory=${at.app}/${at.instance}
+StateDirectoryMode=0700
+LogsDirectory=${at.app}/${at.instance}
+LogsDirectoryMode=0750
+SyslogIdentifier=${at.unit}
+UMask=0077
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+PrivateTmp=yes
+PrivateDevices=yes
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectControlGroups=yes
+RestrictSUIDSGID=yes
+LockPersonality=yes
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+export function backupService(at) {
+    return `[Unit]
+Description=${at.app} (${at.instance}) database backup
+Documentation=file://${at.code}/current/DEPLOY.md
+
+[Service]
+Type=oneshot
+User=${at.unit}
+Group=${at.unit}
+WorkingDirectory=${at.code}/current
+Environment=DOKEBI_CONFIG=${at.settings}
+Environment=DOKEBI_SECRETS=${at.secrets}
+Environment=DOKEBI_BACKUP_DIR=${at.backups}
+# Days, weeks, months of backups to keep (the newest of each).
+Environment=DOKEBI_BACKUP_KEEP=7,4,6
+ExecStart=/usr/bin/node deploy/backup.mjs
+SyslogIdentifier=${at.unit}-backup
+UMask=0077
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+PrivateTmp=yes
+ReadWritePaths=${at.backups}
+`;
+}
+export function backupTimer(at) {
+    return `[Unit]
+Description=Daily database backup of ${at.app} (${at.instance})
+
+[Timer]
+OnCalendar=*-*-* 03:30:00
+RandomizedDelaySec=30min
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`;
+}
+export function composeFile(at) {
+    return `# ${at.app} (${at.instance}): docker compose -f deploy/compose/${at.instance}.yaml up -d --build
+# The container uses the host network, as the systemd unit would: the app listens on
+# 127.0.0.1:${at.port} (settings) behind the reverse proxy of the host, and reaches databases
+# on the host at 127.0.0.1. Settings and secrets are mounted read-only from /etc.
+name: ${at.unit}
+services:
+  app:
+    build:
+      context: ../..
+    image: ${at.app}:${at.instance}
+    init: true
+    network_mode: host
+    # The owner of ${at.secrets} (mode 0600); create that user on the host.
+    user: "\${DOKEBI_UID:-1000}:\${DOKEBI_GID:-1000}"
+    environment:
+      NODE_ENV: production
+      DOKEBI_CONFIG: ${at.settings}
+      DOKEBI_SECRETS: ${at.secrets}
+    volumes:
+      - type: bind
+        source: /etc/${at.app}/${at.instance}
+        target: /etc/${at.app}/${at.instance}
+        read_only: true
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${at.data}
+        target: ${at.data}
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${at.logs}
+        target: ${at.logs}
+        bind:
+          create_host_path: false
+    stop_grace_period: 60s
+    restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: 10m
+        max-file: "5"
+`;
+}
+/** DEPLOY.md: the instance table, setup, a release, rollback, backups (D-0184 §5, §6). */
+export function deployGuide(input) {
+    const { app, target } = input;
+    const systemd = target === 'systemd';
+    const migrate = input.plugins.includes('dokebi-migrate');
+    const db = input.plugins.includes('dokebi-db');
+    const storage = input.plugins.includes('dokebi-storage');
+    const first = input.instances[0];
+    const rows = input.instances
+        .map((at) => `| ${at.instance} | \`${at.unit}\` | 127.0.0.1:${at.port} | \`${at.settings}\` | \`${at.secrets}\` | \`${at.code}/current\` | \`${at.data}\` | \`${at.logs}\` | \`${at.backups}\` | \`${at.database}\` |`)
+        .join('\n');
+    const env = (at) => `DOKEBI_CONFIG=${at.settings} DOKEBI_SECRETS=${at.secrets}`;
+    return `# Deploying ${app}
+
+Written by \`npx dokebi deploy init\` (target: ${target}). Edit it freely: a later \`deploy init\`
+rewrites this file only while it is unchanged (DEPLOY_FILE_KEPT otherwise). Each instance is
+separate on the server: its own system user, port, settings, secrets, code, data, logs, backups
+and database.
+
+| Instance | ${systemd ? 'Unit and user' : 'Compose project'} | Listens on | Settings | Secrets | Code | Data | Logs | Backups | Database |
+|---|---|---|---|---|---|---|---|---|---|
+${rows}
+
+The repository keeps, per instance, \`deploy/<instance>/dokebi.example.yaml\` (the settings
+without secrets: copy it to the settings path) and \`deploy/<instance>/secrets.example.yaml\`
+(the secret paths with placeholders: the values live only in your secret store). The app refuses
+to start while a path of the settings' \`secrets:\` list is empty (CONFIG_SECRETS_MISSING), the
+secrets file is readable by others (CONFIG_SECRETS_UNSAFE) or both files set the same option
+(CONFIG_SECRETS_CONFLICT).${input.secrets.length ? `\n\nSecrets of this app: ${input.secrets.map((path) => `\`${path}\``).join(', ')}.` : ''}
+
+## 1. Prepare the server (once per instance)
+
+Node.js 24 or later${db ? ', the database server and its client tools (pg_dump and pg_restore of the same major version, or the MongoDB Database Tools)' : ''}${systemd ? '' : ', Docker with Compose'} and a reverse proxy (\`npx dokebi deploy proxy --caddy|--nginx --domain <host> --instance <name>\` writes its configuration).
+For each instance (here ${first.instance}):
+
+\`\`\`sh
+sudo useradd --system --home ${first.code} --shell /usr/sbin/nologin ${first.unit}
+sudo install -d -o ${first.unit} -g ${first.unit} -m 0750 ${first.code} ${first.code}/releases
+sudo install -d -o root -g ${first.unit} -m 0750 /etc/${app}/${first.instance}
+sudo install -o ${first.unit} -g ${first.unit} -m 0600 deploy/${first.instance}/dokebi.example.yaml ${first.settings}
+# The secrets file comes from your secret store, never from the repository:
+sudo install -o ${first.unit} -g ${first.unit} -m 0600 /dev/null ${first.secrets}   # then write it (secrets.example.yaml lists the paths)
+${systemd ? '' : `sudo install -d -o ${first.unit} -g ${first.unit} -m 0700 ${first.data}\nsudo install -d -o ${first.unit} -g ${first.unit} -m 0750 ${first.logs}\n`}sudo install -d -o ${first.unit} -g ${first.unit} -m 0700 ${first.backups}
+\`\`\`
+
+Fill the settings file: the placeholders left in it (\`<…>\`), \`dokebi-app.domains\` with the
+public names, and \`dokebi-web.trustProxy\` with the addresses of the reverse proxy (127.0.0.1
+and ::1 when it runs on the same server). ${db ? `Create the database \`${first.database}\` and its own user for this instance; its URL goes in the secrets file.` : ''}
+${systemd ? `\nInstall the units: \`sudo cp deploy/systemd/${first.unit}.service deploy/systemd/${first.unit}-backup.service deploy/systemd/${first.unit}-backup.timer /etc/systemd/system/ && sudo systemctl daemon-reload && sudo systemctl enable ${first.unit} ${first.unit}-backup.timer\`.` : `\nThe compose file runs the container as \`DOKEBI_UID\`:\`DOKEBI_GID\`: set them to the uid and gid of \`${first.unit}\`, the owner of the secrets file.`}
+
+Before the first start, check the instance with the settings it will read:
+
+\`\`\`sh
+cd ${first.code}/current && sudo -u ${first.unit} env NODE_ENV=production ${env(first)} npx -y @dokebi/cli doctor --production
+sudo -u ${first.unit} env ${env(first)} npx -y @dokebi/cli config secrets
+\`\`\`
+
+## 2. Release (every deploy)
+
+Run as the instance's user, in this order; stop at the first step that fails.
+
+1. **Build a new release folder** (never change the running one):
+   \`git clone --depth 1 --branch <tag> <repository> ${first.code}/releases/<id>\`, then in it
+   \`npm ci\`, \`npm run build --if-present\` and \`npm prune --omit=dev\`.${migrate
+        ? `
+2. **Migrate before the switch:** \`${env(first)} npx dokebi-migrate up --phase pre-deploy --json\`
+   in the new folder. Exit code 0 means applied (or nothing to do); 1 means stop: read \`error.code\`.
+   \`LOCK_TIMEOUT\` means another run holds the migration lock (wait, never delete it);
+   \`MIGRATION_TIMEOUT\` a statement waited too long (the file is not recorded).
+   Pre-deploy files only add (a nullable column, a table, an index), so the running release keeps
+   working with them. With \`options.dokebi-migrate.onPending: fail\` the new release refuses to
+   start while a pre-deploy file is pending.`
+        : ''}
+${migrate ? '3' : '2'}. **Switch:** \`ln -sfn releases/<id> ${first.code}/current\` and ${systemd ? `\`sudo systemctl restart ${first.unit}\`` : `\`docker compose -f deploy/compose/${first.instance}.yaml up -d --build\``}.
+   The old process drains on SIGTERM.
+${migrate ? '4' : '3'}. **Check:** \`npx -y @dokebi/cli verify --remote https://<domain> --json\` (TLS, health, security
+   headers; exit 1 on a failure) and \`${systemd ? `journalctl -u ${first.unit} -n 100` : `docker compose -f deploy/compose/${first.instance}.yaml logs --tail 100 app`}\`.${migrate
+        ? `
+5. **Migrate after the switch:** \`${env(first)} npx dokebi-migrate up --json\` applies the
+   post-deploy files (backfills, constraints, dropping what the old release used).`
+        : ''}
+${migrate ? '6' : '4'}. Keep the last 5 release folders; remove older ones.
+
+## 3. Rollback
+
+Point \`current\` back to the previous release and restart ${systemd ? `(\`sudo systemctl restart ${first.unit}\`)` : '(`docker compose ... up -d --build`)'}.${migrate
+        ? ` The
+pre-deploy migrations of the new release stay: they only added, so the previous release works
+with them. Run \`npx dokebi-migrate down --to <name>\` only when a migration itself must go, after
+a backup and knowing what its \`down\` deletes; post-deploy files may have dropped data the
+previous release needs, so restore from a backup instead when one ran.`
+        : ''}
+
+## 4. Backups and restore drills
+${db
+        ? `
+${systemd ? `\`${first.unit}-backup.timer\` runs \`deploy/backup.mjs\` every day at 03:30 (with up to 30 minutes of random delay)` : `Run \`deploy/backup.mjs\` every day from the host's scheduler (it needs Node.js and the database client tools there)`}:
+every \`dokebi-db\` connection with a postgres or mongodb URL is dumped with \`pg_dump -Fc\` or
+\`mongodump --archive --gzip\` into \`${first.backups}/<connection>/<UTC time>.*\` (mode 0600). It
+keeps the newest backup of each of the last 7 days, 4 weeks and 6 months
+(\`DOKEBI_BACKUP_KEEP=7,4,6\`) and prints one JSON line (\`ok\`, the files, their sizes). Passwords
+never reach a command line.
+
+- **Copy them off the server.** A backup on the same disk is lost with the disk: sync
+  \`/var/backups/${app}\` to another place (object storage, another server) after the run, encrypted.
+- **Restore drill, every month** (and after a database upgrade): create an empty scratch database
+  (e.g. \`${first.database}_drill\`), then
+  \`${env(first)} DOKEBI_BACKUP_DIR=${first.backups} DOKEBI_RESTORE_URL=<scratch database URL> node deploy/restore-drill.mjs\`.
+  It restores the newest backup there, refuses the live database, compares tables (or
+  collections) and the migration history with the live one, and prints one JSON line. Drop the
+  scratch database afterwards.
+- **A real restore:** stop the instance, restore the chosen backup into a new database
+  (\`pg_restore --no-owner --dbname=<new database> <file>\` or
+  \`mongorestore --archive=<file> --gzip --nsFrom=<old>.* --nsTo=<new>.*\`), point the URL in the
+  secrets file at it, run \`npx dokebi-migrate status --json\` (it must list no missing file), then
+  start.
+- MySQL and MariaDB connections are not dumped by the script: use
+  \`mysqldump --single-transaction --routines --triggers\` from your scheduler.
+`
+        : `
+This app has no @dokebi/db connection. Back up what it keeps on the server: ${first.data} and
+the settings (the secrets stay in your secret store).
+`}${storage ? `- **Files:** \`${first.data}\` holds the uploaded files of @dokebi/storage (\`dokebi-storage.directory\`); back that folder up with your file backup, at the same time as the database.\n` : ''}- **Secrets:** the secret store is the original of \`secrets.yaml\`; nothing to back up on the server.
+
+## 5. Logs
+
+Records go to stdout as JSON lines: ${systemd ? `\`journalctl -u ${first.unit}\`` : `\`docker compose -f deploy/compose/${first.instance}.yaml logs app\``}.
+A file target of @dokebi/logger writes under \`${first.logs}\`.
+`;
+}
+export function caddyfile(input) {
+    const { at } = input;
+    return `# ${at.app} (${at.instance}): Caddy terminates TLS (automatic certificates) for these names and
+# passes requests to the app on 127.0.0.1:${at.port}. Caddy sets X-Forwarded-For, -Proto and
+# -Host; the app trusts them only from dokebi-web.trustProxy (127.0.0.1 and ::1 here).
+# WebSocket upgrades pass through; responses are not buffered (SSE streams flush at once).
+# The app sets Cache-Control (immutable for built assets, the rules of @dokebi/static) and
+# compresses itself, so Caddy neither caches nor compresses.
+${input.domains.join(', ')} {
+	request_body {
+		max_size ${input.maxBodyBytes}
+	}
+	reverse_proxy 127.0.0.1:${at.port} {
+		flush_interval -1
+		transport http {
+			read_timeout ${input.readTimeoutSeconds}s
+		}
+	}
+	# ${input.live} and ${input.ready} answer as the app answers them (never cached):
+	# what an uptime monitor and dokebi verify --remote read.
+	header ${input.live} Cache-Control no-store
+	header ${input.ready} Cache-Control no-store
+	log {
+		output file /var/log/caddy/${at.unit}.access.log
+	}
+}
+`;
+}
+export function nginxConf(input) {
+    const { at } = input;
+    const names = input.domains.join(' ');
+    const main = input.domains[0];
+    const upstream = at.unit.replaceAll('-', '_');
+    return `# ${at.app} (${at.instance}): nginx terminates TLS for these names and passes requests to the
+# app on 127.0.0.1:${at.port}. The app trusts X-Forwarded-* only from dokebi-web.trustProxy
+# (127.0.0.1 and ::1 here). Certificates: certbot certonly --webroot -w /var/www/letsencrypt -d ${main}
+# Install: copy to /etc/nginx/conf.d/${at.unit}.conf, then nginx -t && systemctl reload nginx.
+
+${input.streams
+        ? `# WebSocket: an Upgrade request keeps its Connection header.
+map $http_upgrade $${upstream}_connection {
+    default upgrade;
+    ''      close;
+}
+
+`
+        : ''}upstream ${upstream} {
+    server 127.0.0.1:${at.port};
+    keepalive 16;
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name ${names};
+    location /.well-known/acme-challenge/ { root /var/www/letsencrypt; }
+    location / { return 308 https://$host$request_uri; }
+}
+
+server {
+    # nginx 1.25.1 and later prefer "http2 on;" (this form still works there, with a warning).
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
+    server_name ${names};
+
+    ssl_certificate     /etc/letsencrypt/live/${main}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/${main}/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_session_cache shared:${upstream}_tls:10m;
+
+    # The app takes bodies up to this size (dokebi-web maxBodyBytes, uploads of @dokebi/storage).
+    client_max_body_size ${input.maxBodyBytes};
+    # The app compresses and sets Cache-Control (immutable built assets, @dokebi/static rules):
+    # nginx neither compresses again nor caches.
+    gzip off;
+
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header X-Forwarded-Host $host;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection ${input.streams ? `$${upstream}_connection` : '""'};
+    # SSE answers carry X-Accel-Buffering: no, so nginx passes each event at once.
+    proxy_read_timeout ${input.readTimeoutSeconds}s;
+    proxy_send_timeout ${input.readTimeoutSeconds}s;
+
+    # Health routes as the app answers them, never cached (monitoring, dokebi verify --remote).
+    location = ${input.live} { proxy_pass http://${upstream}; add_header Cache-Control no-store always; }
+    location = ${input.ready} { proxy_pass http://${upstream}; add_header Cache-Control no-store always; }
+
+    location / {
+        proxy_pass http://${upstream};
+    }
+
+    access_log /var/log/nginx/${at.unit}.access.log;
+    error_log /var/log/nginx/${at.unit}.error.log;
+}
+`;
+}

package/dist/deploy.d.ts

@@ -0,0 +1,46 @@
+import { type InstanceLayout } from './deploy-templates.js';
+export interface DeployWarning {
+    readonly code: string;
+    readonly path?: string;
+    readonly hint: string;
+}
+export interface DeployResult {
+    readonly app: string;
+    readonly changed: string[];
+    readonly unchanged: string[];
+    /** Files you edited since deploy init wrote them: left as they are (DEPLOY_FILE_KEPT). */
+    readonly kept: string[];
+    readonly warnings?: DeployWarning[];
+    readonly nextSteps?: ReadonlyArray<{
+        command: string;
+        why: string;
+    }>;
+}
+export interface DeployInitResult extends DeployResult {
+    readonly target: 'systemd' | 'compose';
+    readonly instances: ReadonlyArray<InstanceLayout>;
+    /** The option paths the settings samples leave to the secrets file (by name). */
+    readonly secrets: readonly string[];
+}
+export interface DeployProxyResult extends DeployResult {
+    readonly proxy: 'caddy' | 'nginx';
+    readonly instance: string;
+    readonly file: string;
+    readonly domains: readonly string[];
+}
+export interface DeployInitOptions {
+    readonly target: 'systemd' | 'compose';
+    readonly instances: readonly string[];
+    readonly port?: number;
+    readonly dryRun?: boolean;
+}
+/** `dokebi deploy init` (D-0184 §2). */
+export declare function deployInit(input: string, options: DeployInitOptions): Promise<DeployInitResult>;
+export interface DeployProxyOptions {
+    readonly proxy: 'caddy' | 'nginx';
+    readonly domains: readonly string[];
+    readonly instance: string;
+    readonly dryRun?: boolean;
+}
+/** `dokebi deploy proxy` (D-0184 §3). */
+export declare function deployProxy(input: string, options: DeployProxyOptions): Promise<DeployProxyResult>;