37071661130

Committed 02 Oct 2026 10:17PM UTC coverage: 80.614% (-0.08%) from 80.693%

Build # 37071661130

Build Type

push

github

Committed by

underpostnet

Commit Message

[deploy] Release the Cyberia repositories from a source channel
Run the lampp deploy from its own source repository
[cyberia-cli] Add the release commands for the product repositories and their lock
Sync stored object layers through the profile
Run both cleanup steps of import-content --clean
Skip stored item ids when importing content
[cyberia] Build a content release from the content revision its deployment locks
Build the local Docker stack images from the workspace sources
Declare the release content of dd-cyberia in one module
Keep the other definitions of a label when a backup restores one
Reload the game servers that serve a written database
Refresh the map preview a write touches
Allow the object layer viewer on the itemledger client
Route an audio binding stated without settings by its event
Seed the default audio of one map through the map audio API
Add the overhead-occlusion foreground behavior
Resolve sagas through instance defaults and summons
Show the saga of every item and map in the studio
Rework the cyberia editors into the studio suite
Serve the authoring context of every map and item
[client-core] Name the build manifest where the repository identity travels
Replace the render payload with the Underpost Build Manifest
Declare the retro font faces once for the shells
Share the document bar and tabs across the studio editors
Add the object layer public route
Give the route to the view raised last when a view closes
Share the submenu landing across the shells
Share undo, drafts and layout across the studio editors
[cli] Render a Docker Compose stack from the stack a project declares
Release a container image by the digest of an exact revision
Add the source-release command for source channels, mirrors and release jobs
Project the keys of one configuration scope into its own Secret
Promote the colour that --traffic names
Remove the instance builds the topology no longer declares
Add the footprint, batch timeout and diagnose options
[db]... (continued)

Coverage Stats

6440 of 8332 branches covered (77.29%)

Branch coverage included in aggregate %.

673 of 731 new or added lines in 30 files covered. (92.07%)

43 existing lines in 3 files now uncovered.

7599 of 9083 relevant lines covered (83.66%)

363.41 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

96.41

/src/cli/docker-compose.js

/**
 * @description Docker Compose pipeline CLI for the local development stack that
 * mirrors the Kubernetes manifests under `manifests/`. Manages dynamic
 * generation of supporting config (nginx router, env-file) and the compose
 * lifecycle (up/down/logs/...). General-purpose: any compose subcommand can be
 * forwarded via `--exec`.
 * @module src/cli/docker-compose.js
 * @namespace UnderpostDockerCompose
 */

import fs from 'fs-extra';
import nodePath from 'path';
import dotenv from 'dotenv';
import { dump as yamlDump } from 'js-yaml';
import { getRootDirectory, shellExec } from '../server/runtime/process.js';
import { loggerFactory } from '../server/ops/logger.js';
import { loadProjectExport } from '../server/runtime/conf.js';
import NginxService from '../runtime/nginx/Nginx.js';

const logger = loggerFactory(import.meta);

/**
 * Reverse-proxy route table derived from
 * manifests/deployment/dd-default-development/proxy.yaml (Contour HTTPProxy).
 * Longer prefixes precede '/' so nginx matches them first.
 * @constant PROXY_HOSTS
 * @memberof UnderpostDockerCompose
 */
const PROXY_HOSTS = [
  {
    host: 'default.net',
    routes: [
      { location: '/peer', target: 'app:4002' },
      { location: '/', target: 'app:4001' },
    ],
  },
  {
    host: 'www.default.net',
    routes: [{ location: '/', target: 'app:4003' }],
  },
];

/** Fallback upstream for unmatched Host headers and the proxy healthcheck. */
const DEFAULT_UPSTREAM = 'app:4001';

/** Prometheus scrape target: the app's /metrics endpoint on its base port. */
const METRICS_TARGET = { service: 'app', port: 4001 };

/** Default deployment identifier (the self-bootstrapping engine deploy). */
const DEFAULT_DEPLOY_ID = 'dd-default';

/**
 * Generated artifact paths (relative to repo root) that `--generate` produces
 * and `--reset` prunes. The working env-file (docker/compose.env) is excluded
 * so a reset never destroys configured credentials.
 */
const GENERATED_ARTIFACTS = [
  'docker/mongodb/entrypoint.sh',
  'docker/nginx/default.conf',
  'docker/prometheus/prometheus.yml',
  'docker/grafana/provisioning',
  'docker/compose.app.yml',
  'docker/compose.env.example',
];

/**
 * @class UnderpostDockerCompose
 * @description Docker Compose development pipeline. A single {@link UnderpostDockerCompose.API.callback}
 * dispatches actions based on flag options, mirroring the cluster CLI pattern.
 * @memberof UnderpostDockerCompose
 */
class UnderpostDockerCompose {
  /**
   * Resolves a repo-root-relative path to an absolute path.
   * @param {string} relPath - Path relative to the engine root.
   * @returns {string} Absolute path.
   * @memberof UnderpostDockerCompose
   */
  static resolve(relPath) {
    return nodePath.isAbsolute(relPath) ? relPath : nodePath.join(getRootDirectory(), relPath);
  }

  /**
   * Resolves the canonical directory for a custom docker-compose workflow,
   * keyed by `--deploy-id` + `--docker-compose-id`:
   * `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>`.
   * Its operator-owned `compose.env` is never generated. See
   * {@link UnderpostDockerCompose.generateStack} for the rest of the directory.
   * Returns null when `--docker-compose-id` is not set (the default,
   * self-generating workflow).
   * @param {object} options - CLI options.
   * @returns {string|null} Repo-root-relative canonical dir, or null.
   * @memberof UnderpostDockerCompose
   */
  static composeIdBase(options = {}) {
    if (!options.dockerComposeId) return null;
    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
    return `engine-private/conf/${deployId}/docker-compose/${options.dockerComposeId}`;
  }

  /**
   * Builds the base `docker compose` invocation with explicit file and env-file,
   * so behavior is independent of the caller's working directory.
   *
   * Custom workflow (`--docker-compose-id`): the compose file, env-file, and
   * project-owned bind-mounted config all live in the canonical dir, so compose
   * runs with `--project-directory` pinned there and no app-override.
   * @param {object} options - CLI options.
   * @returns {string} The base command string (without a subcommand).
   * @memberof UnderpostDockerCompose
   */
  static baseCmd(options = {}) {
    const base = UnderpostDockerCompose.composeIdBase(options);
    if (base) {
      const projectDir = UnderpostDockerCompose.resolve(base);
      const composeFile = UnderpostDockerCompose.resolve(options.composeFile || `${base}/docker-compose.yml`);
      const envFile = UnderpostDockerCompose.resolve(options.envFile || `${base}/compose.env`);
      return `docker compose --project-directory ${projectDir} --env-file ${envFile} -f ${composeFile}`;
    }
    const composeFile = UnderpostDockerCompose.resolve(options.composeFile || 'docker-compose.yml');
    const envFile = UnderpostDockerCompose.resolve(options.envFile || 'docker/compose.env');
    const overrideFile = UnderpostDockerCompose.resolve(options.appOverride || 'docker/compose.app.yml');
    const overrideFlag = fs.existsSync(overrideFile) ? ` -f ${overrideFile}` : '';
    return `docker compose --env-file ${envFile} -f ${composeFile}${overrideFlag}`;
  }

  /**
   * Resolves the app container start command for a deployment, mirroring
   * src/cli/deploy.js. The `dd-default` deploy self-bootstraps a fresh engine
   * (matching manifests/deployment/dd-default-development); any other deploy-id
   * follows the standard deploy command (matching
   * manifests/deployment/dd-test-development and
   * UnderpostDeploy.deploymentYamlPartsFactory's default cmd).
   * @param {string} deployId - Deployment identifier (conf id, e.g. `dd-test`).
   * @param {string} env - Deployment environment (e.g. `development`).
   * @returns {string[]} Ordered shell steps joined with `&&` at render time.
   * @memberof UnderpostDockerCompose
   */
  static appCommand(deployId = DEFAULT_DEPLOY_ID, env = 'development') {
    if (deployId === DEFAULT_DEPLOY_ID)
      return [
        // `$$` escapes to a literal `$` so /bin/sh (not Compose) performs the
        // command/variable substitution at container runtime.
        'cd $$(underpost root)/underpost',
        'node bin new --default-conf --conf-workflow-id template',
        // Point the template .env.example at the Docker service-discovery hosts
        // before `new engine` copies it. The generated dd-engine/.env.development
        // is seeded from this file and is applied over the process env by
        // loadConf (src/server/runtime/conf.js), so without this the engine would fall
        // back to the .env.example localhost defaults for DB_HOST/VALKEY_HOST.
        'sed -i "s#^DB_HOST=.*#DB_HOST=$${DB_HOST}#" .env.example',
        'sed -i "s#^VALKEY_HOST=.*#VALKEY_HOST=$${VALKEY_HOST}#" .env.example',
        'mkdir -p /home/dd',
        'cd /home/dd',
        'underpost new engine',
      ];
    return [`underpost start --build --run ${deployId} ${env}`];
  }

  /**
   * Renders a Compose override file that sets only the `app` service command
   * for the selected deployment. Keeping the command in an override file makes
   * the generator the single source of truth and leaves docker-compose.yml
   * deployment-agnostic.
   * @param {string} deployId - Deployment identifier.
   * @param {string} env - Deployment environment.
   * @returns {string} The override YAML document.
   * @memberof UnderpostDockerCompose
   */
  static appOverrideContent(deployId = DEFAULT_DEPLOY_ID, env = 'development') {
    const steps = UnderpostDockerCompose.appCommand(deployId, env).join(' &&\n        ');
    return `# Generated by 'underpost docker-compose --generate --deploy-id ${deployId}' — do not hand-edit.
# Overrides the app service start command for deploy '${deployId}' (${env}).
services:
  app:
    command:
      - /bin/sh
      - -c
      - >
        ${steps}
`;
  }

  /**
   * Renders the dynamic env-file example content for the compose stack.
   * @returns {string} The env-file template.
   * @memberof UnderpostDockerCompose
   */
  static envExampleContent() {
    return `# Generated by 'underpost docker-compose --generate' — copy to docker/compose.env.
# Loaded explicitly via --env-file so container service-discovery values are not
# overridden by the application's host-local (127.0.0.1) root .env.

# --- Container images ----------------------------------------------------
MONGO_IMAGE=mongo:latest
VALKEY_IMAGE=valkey/valkey:latest
APP_IMAGE=underpost/underpost-engine
APP_TAG=v3.4.5
PROXY_IMAGE=nginx:stable-alpine
PROMETHEUS_IMAGE=prom/prometheus:latest
GRAFANA_IMAGE=grafana/grafana:latest

# --- MongoDB (translation of Secret mongodb-secret) ----------------------
MONGO_INITDB_ROOT_USERNAME=admin
MONGO_INITDB_ROOT_PASSWORD=changeme

# --- Application DB connection (Docker service discovery, not localhost) --
NODE_ENV=development
DB_PROVIDER=mongoose
DB_HOST=mongodb://mongodb:27017
DB_NAME=default
DB_REPLICA_SET=rs0
DB_AUTH_SOURCE=admin

# --- Valkey (Docker service discovery) -----------------------------------
VALKEY_HOST=valkey-service
VALKEY_PORT=6379

# --- Monitoring ----------------------------------------------------------
GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=admin

# --- Host-published ports ------------------------------------------------
PROXY_HTTP_PORT=80
MONGO_HOST_PORT=27017
VALKEY_NODEPORT=32079
PROMETHEUS_PORT=9090
GRAFANA_PORT=3000
APP_PORT_4001=4001
APP_PORT_4002=4002
APP_PORT_4003=4003
APP_PORT_4004=4004
`;
  }

  /**
   * Renders the MongoDB container entrypoint. Mirrors src/db/mongo/MongoBootstrap.js:
   * generates the cluster-auth keyfile, launches mongod (replSet + keyFile + auth),
   * and bootstraps the replica set + root user over the loopback localhost
   * exception (single-node member is the `mongodb` service name so app clients
   * connecting with replicaSet=rs0 resolve a reachable host). Idempotent across
   * restarts: re-runs are no-ops once auth is enforced.
   * @returns {string} entrypoint.sh content.
   * @memberof UnderpostDockerCompose
   */
  static mongoEntrypointContent() {
    return `#!/usr/bin/env bash
# Generated by 'underpost docker-compose --generate' — do not hand-edit.
set -e

KEYFILE=/opt/keyfile/mongodb-keyfile
RS="\${DB_REPLICA_SET:-rs0}"
MEMBER_HOST="mongodb:27017"

if [ ! -s "$KEYFILE" ]; then
  openssl rand -base64 756 > "$KEYFILE"
fi
chmod 400 "$KEYFILE"
chown 999:999 "$KEYFILE"
mkdir -p /data/db
chown -R 999:999 /data/db

# One-time replica-set + root-user bootstrap via the localhost exception,
# performed in the background once mongod accepts loopback connections.
(
  for i in $(seq 1 60); do
    if mongosh --quiet --host 127.0.0.1 --eval 'db.adminCommand({ ping: 1 })' >/dev/null 2>&1; then
      break
    fi
    sleep 1
  done

  cat > /tmp/mongo-bootstrap.js <<JS
var RS = "$RS";
var HOST = "$MEMBER_HOST";
var U = "$MONGO_INITDB_ROOT_USERNAME";
var P = "$MONGO_INITDB_ROOT_PASSWORD";
function waitPrimary() {
  for (var i = 0; i < 60; i++) {
    var h = db.hello();
    if (h.isWritablePrimary) return true;
    sleep(1000);
  }
  return false;
}
var initialized = false;
try {
  var s = rs.status();
  if (s && s.ok === 1) initialized = true;
} catch (e) {
  var m = String(e);
  if (m.indexOf("requires authentication") >= 0 || m.indexOf("not authorized") >= 0 || m.indexOf("Unauthorized") >= 0) {
    initialized = true;
  } else if (m.indexOf("NotYetInitialized") < 0 && m.indexOf("no replset config") < 0) {
    throw e;
  }
}
if (!initialized) {
  rs.initiate({ _id: RS, members: [{ _id: 0, host: HOST }] });
  waitPrimary();
  var admin = db.getSiblingDB("admin");
  try {
    admin.createUser({ user: U, pwd: P, roles: [{ role: "root", db: "admin" }] });
    print("BOOTSTRAP_USER_CREATED");
  } catch (e) {
    var s2 = String(e);
    if (s2.indexOf("already exists") < 0 && s2.indexOf("not authorized") < 0 && s2.indexOf("requires authentication") < 0) {
      throw e;
    }
    print("BOOTSTRAP_USER_SKIP");
  }
  print("BOOTSTRAP_DONE");
} else {
  print("BOOTSTRAP_ALREADY_INITIALIZED");
}
JS

  mongosh --quiet --host 127.0.0.1 /tmp/mongo-bootstrap.js > /tmp/mongo-bootstrap.log 2>&1 || true
) &

exec gosu mongodb mongod \\
  --replSet "$RS" --auth --clusterAuthMode keyFile --keyFile "$KEYFILE" --bind_ip_all
`;
  }

  /**
   * Renders the Prometheus scrape config (mirrors manifests/prometheus).
   * @returns {string} prometheus.yml content.
   * @memberof UnderpostDockerCompose
   */
  static prometheusContent() {
    return `# Generated by 'underpost docker-compose --generate' — do not hand-edit.
global:
  scrape_interval: 30s
  evaluation_interval: 30s

scrape_configs:
  - job_name: 'underpost-app'
    metrics_path: /metrics
    scheme: http
    static_configs:
      - targets: ['${METRICS_TARGET.service}:${METRICS_TARGET.port}']
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']
`;
  }

  /**
   * Renders the Grafana datasource provisioning file wiring the Prometheus
   * service as the default datasource.
   * @returns {string} datasource.yml content.
   * @memberof UnderpostDockerCompose
   */
  static grafanaDatasourceContent() {
    return `# Generated by 'underpost docker-compose --generate' — do not hand-edit.
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    editable: true
`;
  }

  /**
   * Renders the IPFS (Kubo) init hook: binds the RPC API and the gateway to every interface, so
   * the other services reach the daemon at `http://ipfs:5001`. Mirrors manifests/ipfs/configmap.yaml.
   * @returns {string} configure-ipfs.sh content.
   * @memberof UnderpostDockerCompose
   */
  static ipfsInitContent() {
    return `#!/bin/sh
# Generated by 'underpost docker-compose --generate' — do not hand-edit.
set -e

ipfs config Addresses.API /ip4/0.0.0.0/tcp/5001
ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080
ipfs config --json Swarm.ConnMgr.HighWater 2000
ipfs config --json Datastore.BloomFilterSize 1048576
ipfs config Datastore.StorageMax 100GB
`;
  }

  /**
   * Renders a custom workflow from the stack its project declares: the `composeStacks[<docker-compose-id>]`
   * export of `src/projects/<project>/compose-stack.js`. The stack gets `{ deployId, env, composeEnv, nginx }`,
   * declares its gateway on `nginx` and returns the compose document. The rendering holds
   * `docker-compose.yml`, `nginx.conf`, and the platform init script of a `mongodb` and an `ipfs` service.
   * @param {object} options - CLI options.
   * @returns {Promise<Object<string,string>|null>} Content by absolute path; null without a declared stack.
   * @throws {Error} When the canonical directory lacks a file the workflow reads.
   * @memberof UnderpostDockerCompose
   */
  static async renderStack(options = {}) {
    const base = UnderpostDockerCompose.composeIdBase(options);
    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
    const envFile = UnderpostDockerCompose.resolve(options.envFile || `${base}/compose.env`);
    const composeFile = UnderpostDockerCompose.resolve(options.composeFile || `${base}/docker-compose.yml`);
    const stack = (await loadProjectExport(deployId, 'compose-stack.js', 'composeStacks'))?.[options.dockerComposeId];
    const missing = (stack ? [envFile] : [composeFile, envFile]).filter((path) => !fs.existsSync(path));
    if (missing.length) throw new Error(`Custom Docker Compose workflow is missing: ${missing.join(', ')}`);
    if (!stack) return null;

    const origin = `'underpost docker-compose --generate --deploy-id ${deployId} --docker-compose-id ${options.dockerComposeId}'`;
    const nginx = new NginxService();
    const compose = stack({
      deployId,
      env: options.env || 'development',
      composeEnv: dotenv.parse(fs.readFileSync(envFile, 'utf8')),
      nginx,
    });
    const dir = UnderpostDockerCompose.resolve(base);
    const files = {
      [composeFile]: `# Generated by ${origin} — do not hand-edit.\n${yamlDump(compose, { lineWidth: -1, noRefs: true })}`,
    };
    if (nginx.servers.length) files[`${dir}/nginx.conf`] = nginx.render({ origin });
    if (compose.services?.mongodb)
      files[`${dir}/mongodb/entrypoint.sh`] = UnderpostDockerCompose.mongoEntrypointContent();
    if (compose.services?.ipfs) files[`${dir}/ipfs/configure-ipfs.sh`] = UnderpostDockerCompose.ipfsInitContent();
    return files;
  }

  /**
   * Writes the rendering of a custom workflow (see {@link UnderpostDockerCompose.renderStack}). Without a
   * declared stack, the directory's own `docker-compose.yml` is used as-is.
   * @param {object} options - CLI options.
   * @returns {Promise<void>}
   * @memberof UnderpostDockerCompose
   */
  static async generateStack(options = {}) {
    const files = await UnderpostDockerCompose.renderStack(options);
    if (!files) {
      logger.info('custom Docker Compose workflow uses canonical files as-is', {
        path: UnderpostDockerCompose.composeIdBase(options),
      });
      return;
    }
    for (const [target, content] of Object.entries(files)) {
      fs.mkdirpSync(nodePath.dirname(target));
      fs.writeFileSync(target, content, target.endsWith('.sh') ? { mode: 0o755 } : 'utf8');
    }
    logger.info('custom Docker Compose workflow generated', {
      deployId: options.deployId || DEFAULT_DEPLOY_ID,
      env: options.env || 'development',
      written: Object.keys(files),
    });
  }

  /**
   * Renders all dynamic supporting files: the nginx reverse-proxy config (from
   * PROXY_HOSTS), the monitoring configs (Prometheus + Grafana datasource), and
   * the env-file example. Creates a working env-file from the example only when
   * one does not already exist (never overwrites credentials). A custom workflow
   * renders its own stack instead: see {@link UnderpostDockerCompose.generateStack}.
   * @param {object} options - CLI options.
   * @returns {Promise<void>}
   * @memberof UnderpostDockerCompose
   */
  static async generate(options = {}) {
    if (UnderpostDockerCompose.composeIdBase(options)) return UnderpostDockerCompose.generateStack(options);

    const nginx = new NginxService();
    for (const { host, routes } of PROXY_HOSTS)
      nginx.addServer({
        names: [host],
        health: true,
        locations: routes.map(({ location, target }) => ({ match: location, proxy: target })),
      });
    nginx.addServer({
      listen: ['80 default_server'],
      health: true,
      locations: [{ match: '/', proxy: DEFAULT_UPSTREAM }],
    });
    nginx.writeConf(UnderpostDockerCompose.resolve(options.nginxConf || 'docker/nginx/default.conf'), {
      origin: "'underpost docker-compose --generate'",
    });

    const mongoEntrypointPath = UnderpostDockerCompose.resolve('docker/mongodb/entrypoint.sh');
    fs.mkdirpSync(nodePath.dirname(mongoEntrypointPath));
    fs.writeFileSync(mongoEntrypointPath, UnderpostDockerCompose.mongoEntrypointContent(), { mode: 0o755 });
    logger.info('mongodb entrypoint written', { path: mongoEntrypointPath });

    const promPath = UnderpostDockerCompose.resolve('docker/prometheus/prometheus.yml');
    fs.mkdirpSync(nodePath.dirname(promPath));
    fs.writeFileSync(promPath, UnderpostDockerCompose.prometheusContent(), 'utf8');
    const grafanaDsPath = UnderpostDockerCompose.resolve('docker/grafana/provisioning/datasources/datasource.yml');
    fs.mkdirpSync(nodePath.dirname(grafanaDsPath));
    fs.writeFileSync(grafanaDsPath, UnderpostDockerCompose.grafanaDatasourceContent(), 'utf8');
    logger.info('monitoring config written', { prometheus: promPath, grafanaDatasource: grafanaDsPath });

    const examplePath = UnderpostDockerCompose.resolve('docker/compose.env.example');
    fs.mkdirpSync(nodePath.dirname(examplePath));
    fs.writeFileSync(examplePath, UnderpostDockerCompose.envExampleContent(), 'utf8');
    logger.info('env example written', { path: examplePath });

    const envPath = UnderpostDockerCompose.resolve(options.envFile || 'docker/compose.env');
    if (!fs.existsSync(envPath)) {
      fs.copySync(examplePath, envPath);
      logger.warn('created working env-file from example — set real credentials', { path: envPath });
    } else logger.info('working env-file already present (left untouched)', { path: envPath });

    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
    const env = options.env || 'development';
    const overridePath = UnderpostDockerCompose.resolve(options.appOverride || 'docker/compose.app.yml');
    fs.writeFileSync(overridePath, UnderpostDockerCompose.appOverrideContent(deployId, env), 'utf8');
    logger.info('app command override written', { path: overridePath, deployId, env });
  }

  /**
   * Installs Docker Engine and the Compose v2 plugin on RHEL-compatible hosts
   * (Rocky Linux) from the official Docker CE repository. Idempotent and
   * host-safe: skips installation when `docker compose` already works (unless
   * `--force`), validates the platform, enables the service, and adds the
   * invoking user to the `docker` group.
   * @param {object} options - CLI options.
   * @param {boolean} [options.force] - Reinstall even if Compose is already present.
   * @returns {void}
   * @memberof UnderpostDockerCompose
   */
  static install(options = {}) {
    if (process.platform !== 'linux') {
      logger.warn('docker-compose --install only supports Linux (RHEL/Rocky); skipping', {
        platform: process.platform,
      });
      return;
    }

    if (!fs.existsSync('/etc/redhat-release')) {
      logger.warn('Host does not look RHEL-compatible (/etc/redhat-release missing); proceeding with dnf anyway');
    }

    if (!options.force) {
      const probe = shellExec('docker compose version', { silent: true, silentOnError: true });
      if (probe && probe.code === 0) {
        logger.info('Docker Compose already installed; skipping (use --force to reinstall)', {
          version: (probe.stdout || '').trim(),
        });
        return;
      }
    }

    shellExec(`sudo dnf -y install dnf-plugins-core`);
    shellExec(`sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo`);
    shellExec(`sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin`);

    shellExec(`sudo systemctl enable --now docker`);

    const user = options.user || process.env.SUDO_USER || process.env.USER || '';
    if (user && user !== 'root') {
      shellExec(`sudo groupadd docker 2>/dev/null || true`);
      shellExec(`sudo usermod -aG docker ${user}`);
      logger.info(`Added '${user}' to the docker group — log out/in (or run 'newgrp docker') to use docker rootless`);
    }

    const verify = shellExec('docker compose version', { silent: true, silentOnError: true, stdout: true });
    logger.info('Docker Compose installation complete', { version: `${verify || ''}`.trim() });
  }

  /**
   * Comprehensive reset of the Docker Compose stack — the compose equivalent of
   * `cluster --reset` in src/cli/cluster.js. Tears down all stack containers,
   * the project network, and the named volumes (destroying persisted MongoDB /
   * Valkey / Prometheus / Grafana data), removes orphans, and prunes generated
   * artifacts so the next `--up` is a clean slate. The working env-file
   * (credentials) is preserved unless `--force` is passed.
   * @param {object} options - CLI options.
   * @param {boolean} [options.force] - Also remove the working env-file (docker/compose.env).
   * @returns {void}
   * @memberof UnderpostDockerCompose
   */
  static reset(options = {}) {
    logger.info('=== DOCKER COMPOSE RESET (destroys containers, network, and volume data) ===');

    // Phase 1: tear down containers, orphans, named volumes, and compose-built images.
    shellExec(`${UnderpostDockerCompose.baseCmd(options)} down --remove-orphans --volumes --rmi local`, {
      silentOnError: true,
    });

    // A named custom workflow owns every file beneath its canonical directory.
    // Reset tears down Docker resources but never prunes project-owned files.
    const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
    if (composeIdBase) {
      logger.info('Docker Compose reset complete. Run `--up` to recreate the stack.');
      return;
    }

    // Phase 2: prune generated artifacts (regenerated on the next --generate/--up).
    const artifacts = options.force
      ? [...GENERATED_ARTIFACTS, options.envFile || 'docker/compose.env']
      : GENERATED_ARTIFACTS;
    for (const rel of artifacts) {
      const target = UnderpostDockerCompose.resolve(rel);
      if (fs.existsSync(target)) {
        fs.removeSync(target);
        logger.info('removed generated artifact', { path: target });
      }
    }

    logger.info('Docker Compose reset complete. Run `--up` to recreate the stack.');
  }

  static API = {
    /**
     * @method callback
     * @description Single CLI entrypoint for the docker-compose pipeline. The
     * action is selected by flag options; multiple lifecycle flags may be
     * combined (e.g. `--generate --up`). When no action flag is supplied it
     * defaults to `--up`.
     * @param {string} [target] - Optional service name (logs/shell/restart) or
     *   passthrough subcommand context.
     * @param {object} [options] - CLI options.
     * @param {boolean} [options.install] - Install Docker + Compose on RHEL/Rocky hosts.
     * @param {boolean} [options.reset] - Comprehensive teardown of the whole stack (containers, network, volumes) + prune generated artifacts.
     * @param {boolean} [options.force] - Force reinstall (--install), remove volumes (--down), or also drop the env-file (--reset).
     * @param {boolean} [options.generate] - Render nginx config + env-file.
     * @param {boolean} [options.up] - Start the full stack detached (implies generate).
     * @param {boolean} [options.down] - Stop and remove containers.
     * @param {boolean} [options.volumes] - With --down, also remove named volumes (destroys data).
     * @param {boolean} [options.restart] - Restart services (optionally a single `target`).
     * @param {boolean} [options.build] - With --up rebuild images; alone, `build --no-cache`.
     * @param {boolean} [options.pull] - Pull upstream images.
     * @param {boolean} [options.logs] - Follow logs (optionally a single `target`).
     * @param {boolean} [options.status] - Show a formatted status table.
     * @param {boolean} [options.shell] - Open an interactive shell in `target` (default: app).
     * @param {string} [options.exec] - General-purpose passthrough docker compose subcommand.
     * @param {string} [options.deployId] - Deployment to run as the app (default: dd-default). `dd-default` self-bootstraps a fresh engine; any other id runs the standard `underpost start` command.
     * @param {string} [options.dockerComposeId] - Custom-workflow selector. When set, use the canonical stack at `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>/`, rendered from its project stack when the project declares one.
     * @param {string} [options.env] - Deployment environment of a non-default deploy id or a custom stack (default: development).
     * @param {string} [options.composeFile] - Override compose file path.
     * @param {string} [options.envFile] - Override env-file path.
     * @param {string} [options.nginxConf] - Override generated nginx config path.
     * @param {string} [options.appOverride] - Override generated app-command override path.
     * @returns {Promise<void>}
     * @memberof UnderpostDockerCompose
     */
    async callback(target = '', options = {}) {
      try {
        if (options.install) {
          UnderpostDockerCompose.install(options);
          const onlyInstall = !options.up && !options.down && !options.generate && !options.exec;
          if (onlyInstall) return;
        }

        if (options.reset) {
          UnderpostDockerCompose.reset(options);
          const onlyReset = !options.up && !options.generate;
          if (onlyReset) return;
        }

        // "Bring up" is the explicit --up or the no-action default.
        const isUp =
          options.up ||
          !(
            options.exec ||
            options.down ||
            options.restart ||
            options.build ||
            options.pull ||
            options.logs ||
            options.status ||
            options.shell ||
            options.generate
          );

        // Generate dynamic config BEFORE composing the invocation: baseCmd()
        // conditionally includes `-f compose.app.yml`, so the override must
        // exist first (notably after --reset, which prunes it).
        if (isUp || options.generate) await UnderpostDockerCompose.generate(options);

        const base = UnderpostDockerCompose.baseCmd(options);

        if (options.exec) {
          shellExec(`${base} ${options.exec}`);
          return;
        }

        if (isUp) {
          shellExec(`${base} up -d${options.build ? ' --build' : ''}`);
          return;
        }

        if (options.down) {
          shellExec(`${base} down --remove-orphans${options.volumes ? ' --volumes' : ''}`);
          return;
        }

        if (options.restart) {
          shellExec(`${base} restart${target ? ` ${target}` : ''}`);
          return;
        }

        if (options.build) {
          shellExec(`${base} build --no-cache${target ? ` ${target}` : ''}`);
          return;
        }

        if (options.pull) {
          shellExec(`${base} pull`);
          return;
        }

        if (options.logs) {
          shellExec(`${base} logs -f --tail=200${target ? ` ${target}` : ''}`);
          return;
        }

        if (options.status) {
          shellExec(`${base} ps --format 'table {{.Name}}\\t{{.Service}}\\t{{.Status}}\\t{{.Ports}}'`);
          return;
        }

        if (options.shell) {
          const service = target || 'app';
          shellExec(`${base} exec ${service} ${service === 'app' ? '/bin/bash' : '/bin/sh'}`);
          return;
        }

        // Remaining case: --generate alone (config already written above).
      } catch (error) {
        logger.error(error);
        process.exit(1);
      }
    },
  };
}

export default UnderpostDockerCompose;

underpostnet / engine-cyberia / 37071661130

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous