@aopslabs/aops 0.2.0 → 0.3.0

package/dist/lib/setup-docker-server.js

@@ -0,0 +1,666 @@
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveCommunityInstanceLayout } from './community-instance-layout.js';
+import { resolveCommunityNativeDefaultSourceRoot } from './community-native-lifecycle.js';
+import { openExternalUrl } from './external-url.js';
+const DEFAULT_PORT = 5900;
+const SERVER_PACKAGE_NAME = '@aopslabs/aops-server';
+const POSTGRES_IMAGE = 'postgres:17-bookworm@sha256:4f736ae292687621d4dbe0d499ffd024a36bd2ee7d8ca6f2ccd4c800f047b394';
+const MANAGED_LABEL_KEY = 'io.aopslab.aops-platform.managed-by';
+const MANAGED_LABEL_VALUE = 'aops-cli';
+const MANAGED_LABEL = `${MANAGED_LABEL_KEY}=${MANAGED_LABEL_VALUE}`;
+function runDockerDefault(args) {
+    return spawnSync('docker', [...args], { encoding: 'utf8', windowsHide: true });
+}
+function runDockerRequired(runDocker, args, step) {
+    const result = runDocker(args);
+    if (result.status !== 0)
+        throw new Error(`setup_docker_${step}_failed`);
+    return output(result);
+}
+function atomicPrivateEnvironment(target, content) {
+    const parent = path.dirname(target);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    writeFileSync(target, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    chmodSync(target, 0o600);
+}
+function removePrivateEnvironment(target) {
+    rmSync(target, { force: true });
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function probeHealth(origin) {
+    try {
+        const response = await fetch(`${origin}/api/health`, {
+            method: 'GET',
+            signal: AbortSignal.timeout(5_000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitFor(timeoutMilliseconds, sleep, probe, code) {
+    const deadline = Date.now() + timeoutMilliseconds;
+    while (Date.now() < deadline) {
+        if (await probe())
+            return;
+        await sleep(1_000);
+    }
+    throw new Error(code);
+}
+function probePort(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.unref();
+        server.once('error', () => resolve(false));
+        server.listen({ host: '127.0.0.1', port, exclusive: true }, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+function readServerVersion() {
+    const packageManifest = fileURLToPath(new URL('../../package.json', import.meta.url));
+    try {
+        const manifest = JSON.parse(readFileSync(packageManifest, 'utf8'));
+        if (typeof manifest.aopsDockerServerVersion === 'string'
+            && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(manifest.aopsDockerServerVersion))
+            return manifest.aopsDockerServerVersion;
+    }
+    catch {
+    }
+    const root = resolveCommunityNativeDefaultSourceRoot();
+    const candidates = [
+        path.join(root, 'package.json'),
+        path.join(root, 'apps', 'aops-server', 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const manifest = JSON.parse(readFileSync(candidate, 'utf8'));
+            if (manifest.name === SERVER_PACKAGE_NAME
+                && typeof manifest.version === 'string'
+                && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(manifest.version))
+                return manifest.version;
+        }
+        catch {
+        }
+    }
+    throw new Error('setup_docker_server_package_identity_unavailable');
+}
+function normalizeArchitecture(arch) {
+    if (arch === 'x64')
+        return 'amd64';
+    if (arch === 'arm64')
+        return 'arm64';
+    throw new Error('setup_docker_architecture_unsupported');
+}
+function validatePort(value) {
+    const port = value ?? DEFAULT_PORT;
+    if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+        throw new Error('setup_docker_port_invalid');
+    }
+    return port;
+}
+function output(result) {
+    return String(result.stdout ?? '').trim();
+}
+function readEnvironmentPort(environmentPath, readEnvironment) {
+    try {
+        const content = readEnvironment(environmentPath);
+        const line = content.split(/\r?\n/).find((candidate) => candidate.startsWith('AOPS_PUBLIC_PORT='));
+        if (!line)
+            return undefined;
+        const value = Number.parseInt(line.slice('AOPS_PUBLIC_PORT='.length), 10);
+        return Number.isSafeInteger(value) && value >= 1 && value <= 65_535 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function inspectDockerResource(runDocker, kind, name) {
+    const result = runDocker([kind, 'inspect', name]);
+    if (result.status !== 0) {
+        const inspection = detail(result, 'inspection failed');
+        if (/no such|not found/i.test(inspection)) {
+            return { state: 'absent', owned: false, present: false, inspectable: true };
+        }
+        return { state: 'unknown', owned: false, present: false, inspectable: false };
+    }
+    try {
+        const values = JSON.parse(output(result));
+        const first = values[0];
+        const labels = kind === 'container' ? first?.Config?.Labels : first?.Labels;
+        const owned = labels?.[MANAGED_LABEL_KEY] === MANAGED_LABEL_VALUE;
+        const state = kind === 'container' && typeof first?.State?.Status === 'string'
+            ? first.State.Status
+            : 'present';
+        return { state, owned, present: true, inspectable: true };
+    }
+    catch {
+        return { state: 'unknown', owned: false, present: true, inspectable: false };
+    }
+}
+function dockerSetupIdentity(options, dependencies) {
+    const platform = dependencies.platform ?? process.platform;
+    if (!['win32', 'linux', 'darwin'].includes(platform))
+        throw new Error('setup_docker_platform_unsupported');
+    const architecture = normalizeArchitecture(dependencies.arch ?? process.arch);
+    const layout = resolveCommunityInstanceLayout({
+        instanceId: options.instance,
+        platform,
+        environment: dependencies.environment,
+        homeDirectory: dependencies.homeDirectory,
+    });
+    const environmentPath = path.join(layout.configDir, 'docker.env');
+    const environmentPort = (dependencies.pathExists ?? existsSync)(environmentPath)
+        ? readEnvironmentPort(environmentPath, dependencies.readPrivateEnvironment ?? ((target) => readFileSync(target, 'utf8')))
+        : undefined;
+    const port = validatePort(options.port ?? environmentPort);
+    const serverVersion = (dependencies.resolveServerVersion ?? readServerVersion)();
+    const image = options.image ?? `aops-platform:registry-${serverVersion}-${architecture}`;
+    const pullImage = options.pullImage ?? `ghcr.io/eeemzs/aops-platform:registry-${serverVersion}-${architecture}`;
+    if ([image, pullImage].some((candidate) => candidate.trim() !== candidate || candidate.length === 0 || /[\r\n\0]/.test(candidate))) {
+        throw new Error('setup_docker_image_invalid');
+    }
+    const prefix = `aops-${layout.instanceId}`;
+    return Object.freeze({
+        instance: layout.instanceId,
+        image,
+        pullImage,
+        port,
+        origin: `http://127.0.0.1:${port}`,
+        environmentPath,
+        resources: Object.freeze({
+            serverContainer: `${prefix}-server`,
+            postgresContainer: `${prefix}-postgres`,
+            network: `${prefix}-network`,
+            serverDataVolume: `${prefix}-server-data`,
+            postgresDataVolume: `${prefix}-postgres-data`,
+        }),
+    });
+}
+function detail(result, fallback) {
+    return String(result.stderr ?? result.stdout ?? fallback).trim() || fallback;
+}
+function resourceCheck(runDocker, kind, name) {
+    const result = runDocker([kind, 'inspect', name]);
+    if (result.status === 0) {
+        return { id: `${kind}:${name}`, status: 'fail', summary: `${name} already exists; choose repair or another instance.` };
+    }
+    const inspection = detail(result, 'inspection failed');
+    return /no such|not found/i.test(inspection)
+        ? { id: `${kind}:${name}`, status: 'pass', summary: `${name} is available.` }
+        : { id: `${kind}:${name}`, status: 'fail', summary: `${name} could not be inspected: ${inspection}` };
+}
+function imageCheck(runDocker, image, serverVersion, architecture, pullImage) {
+    const result = runDocker(['image', 'inspect', image]);
+    if (result.status !== 0) {
+        return {
+            id: 'image',
+            status: 'info',
+            summary: `${image} is not on this computer yet; setup will download ${pullImage}.`,
+        };
+    }
+    try {
+        const inspected = JSON.parse(output(result));
+        const first = inspected[0];
+        const labels = first?.Config?.Labels ?? {};
+        const valid = first?.Os === 'linux'
+            && first.Architecture === architecture
+            && labels['io.aopslab.aops-platform.install-mode'] === 'registry'
+            && labels['io.aopslab.aops-platform.server-version'] === serverVersion
+            && labels['org.opencontainers.image.title'] === 'AOPS Server';
+        return valid
+            ? { id: 'image', status: 'pass', summary: `${image} is the expected server-only image.` }
+            : { id: 'image', status: 'fail', summary: `${image} does not match the AOPS Server ${serverVersion} contract.` };
+    }
+    catch {
+        return { id: 'image', status: 'fail', summary: `${image} returned an unreadable inspection result.` };
+    }
+}
+export async function inspectDockerServerSetupPreview(options = {}, dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    if (!['win32', 'linux', 'darwin'].includes(platform)) {
+        throw new Error('setup_docker_platform_unsupported');
+    }
+    const architecture = normalizeArchitecture(dependencies.arch ?? process.arch);
+    const port = validatePort(options.port);
+    const layout = resolveCommunityInstanceLayout({
+        instanceId: options.instance,
+        platform,
+        environment: dependencies.environment,
+        homeDirectory: dependencies.homeDirectory,
+    });
+    const serverVersion = (dependencies.resolveServerVersion ?? readServerVersion)();
+    const image = options.image ?? `aops-platform:registry-${serverVersion}-${architecture}`;
+    const pullImage = options.pullImage
+        ?? `ghcr.io/eeemzs/aops-platform:registry-${serverVersion}-${architecture}`;
+    if ([image, pullImage].some((candidate) => candidate.trim() !== candidate || candidate.length === 0 || /[\r\n\0]/.test(candidate))) {
+        throw new Error('setup_docker_image_invalid');
+    }
+    const prefix = `aops-${layout.instanceId}`;
+    const resources = Object.freeze({
+        serverContainer: `${prefix}-server`,
+        postgresContainer: `${prefix}-postgres`,
+        network: `${prefix}-network`,
+        serverDataVolume: `${prefix}-server-data`,
+        postgresDataVolume: `${prefix}-postgres-data`,
+    });
+    const environmentPath = path.join(layout.configDir, 'docker.env');
+    const runDocker = dependencies.runDocker ?? runDockerDefault;
+    const checks = [];
+    const daemon = runDocker(['info', '--format', '{{json .ServerVersion}}']);
+    checks.push(daemon.status === 0
+        ? { id: 'docker', status: 'pass', summary: `Docker is ready (${output(daemon) || 'server available'}).` }
+        : { id: 'docker', status: 'fail', summary: `Docker is not ready: ${detail(daemon, 'start Docker Desktop')}` });
+    if (daemon.status === 0) {
+        checks.push(imageCheck(runDocker, image, serverVersion, architecture, pullImage));
+        checks.push(resourceCheck(runDocker, 'container', resources.serverContainer));
+        checks.push(resourceCheck(runDocker, 'container', resources.postgresContainer));
+        checks.push(resourceCheck(runDocker, 'network', resources.network));
+        checks.push(resourceCheck(runDocker, 'volume', resources.serverDataVolume));
+        checks.push(resourceCheck(runDocker, 'volume', resources.postgresDataVolume));
+    }
+    else {
+        checks.push({ id: 'image', status: 'fail', summary: 'Start Docker to inspect the local AOPS image.' });
+    }
+    const available = await (dependencies.portAvailable ?? probePort)(port);
+    checks.push(available
+        ? { id: 'port', status: 'pass', summary: `127.0.0.1:${port} is available.` }
+        : { id: 'port', status: 'fail', summary: `127.0.0.1:${port} is already in use.` });
+    checks.push((dependencies.pathExists ?? existsSync)(environmentPath)
+        ? { id: 'environment', status: 'fail', summary: `${environmentPath} already exists; use settings or repair.` }
+        : { id: 'environment', status: 'pass', summary: `${environmentPath} is available.` });
+    const failed = checks.filter((check) => check.status === 'fail');
+    return Object.freeze({
+        schemaVersion: 1,
+        command: 'setup.docker.preview',
+        mutationFree: true,
+        status: failed.length === 0 ? 'ready' : 'action-required',
+        method: Object.freeze({
+            id: 'docker-managed',
+            title: 'Docker (recommended)',
+            recommended: true,
+            description: 'AOPS Server and PostgreSQL run in isolated Docker resources.',
+        }),
+        generated: Object.freeze({
+            instance: layout.instanceId,
+            image,
+            pullImage,
+            port,
+            origin: `http://127.0.0.1:${port}`,
+            environmentPath,
+            postgresPassword: 'generated-during-apply',
+            resources,
+        }),
+        checks: Object.freeze(checks),
+        nextActions: Object.freeze(failed.map((check) => check.summary)),
+        applyAvailable: failed.length === 0,
+    });
+}
+export async function applyDockerServerSetup(options = {}, dependencies = {}) {
+    const preview = await inspectDockerServerSetupPreview(options, dependencies);
+    if (!preview.applyAvailable) {
+        throw new Error(`setup_docker_not_ready:${preview.nextActions[0] ?? 'review_preview'}`);
+    }
+    const runDocker = dependencies.runDocker ?? runDockerDefault;
+    const sleep = dependencies.sleep ?? delay;
+    const writeEnvironment = dependencies.writePrivateEnvironment ?? atomicPrivateEnvironment;
+    const removeEnvironment = dependencies.removePrivateEnvironment ?? removePrivateEnvironment;
+    const password = (dependencies.createSecret ?? (() => randomBytes(32).toString('base64url')))();
+    if (!/^[A-Za-z0-9_-]{32,128}$/.test(password)) {
+        throw new Error('setup_docker_generated_secret_invalid');
+    }
+    const { resources } = preview.generated;
+    const created = [];
+    const steps = [];
+    let environmentWritten = false;
+    try {
+        const imageState = preview.checks.find((check) => check.id === 'image');
+        if (imageState?.status === 'info') {
+            runDockerRequired(runDocker, ['pull', preview.generated.pullImage], 'image_pull');
+            runDockerRequired(runDocker, ['image', 'tag', preview.generated.pullImage, preview.generated.image], 'image_tag');
+        }
+        const verifiedImage = imageCheck(runDocker, preview.generated.image, (dependencies.resolveServerVersion ?? readServerVersion)(), normalizeArchitecture(dependencies.arch ?? process.arch), preview.generated.pullImage);
+        if (verifiedImage.status !== 'pass')
+            throw new Error('setup_docker_image_contract_invalid');
+        steps.push({ id: imageState?.status === 'info' ? 'image-pull' : 'image-check', status: 'completed' });
+        const encodedPassword = encodeURIComponent(password);
+        const environmentContent = [
+            'POSTGRES_DB=aops',
+            'POSTGRES_USER=aops',
+            `POSTGRES_PASSWORD=${password}`,
+            `AOPS_PG_URL=postgresql://aops:${encodedPassword}@postgres:5432/aops`,
+            'AOPS_POSTGRES_TLS=disable',
+            `AOPS_PUBLIC_PORT=${preview.generated.port}`,
+            'AOPS_AUTH_PROVIDER=trusted-local',
+            '',
+        ].join('\n');
+        writeEnvironment(preview.generated.environmentPath, environmentContent);
+        environmentWritten = true;
+        steps.push({ id: 'environment', status: 'completed' });
+        runDockerRequired(runDocker, ['network', 'create', '--label', MANAGED_LABEL, resources.network], 'network_create');
+        created.push({ kind: 'network', name: resources.network });
+        for (const name of [resources.serverDataVolume, resources.postgresDataVolume]) {
+            runDockerRequired(runDocker, ['volume', 'create', '--label', MANAGED_LABEL, name], 'volume_create');
+            created.push({ kind: 'volume', name });
+        }
+        runDockerRequired(runDocker, [
+            'run', '--detach', '--name', resources.postgresContainer,
+            '--label', MANAGED_LABEL,
+            '--restart', 'unless-stopped',
+            '--network', resources.network,
+            '--network-alias', 'postgres',
+            '--env-file', preview.generated.environmentPath,
+            '--volume', `${resources.postgresDataVolume}:/var/lib/postgresql/data`,
+            POSTGRES_IMAGE,
+        ], 'postgres_create');
+        created.push({ kind: 'container', name: resources.postgresContainer });
+        await waitFor(90_000, sleep, () => {
+            const result = runDocker([
+                'exec', resources.postgresContainer,
+                'pg_isready', '-U', 'aops', '-d', 'aops',
+            ]);
+            return result.status === 0;
+        }, 'setup_docker_postgres_timeout');
+        steps.push({ id: 'postgres', status: 'completed' });
+        runDockerRequired(runDocker, [
+            'run', '--detach', '--name', resources.serverContainer,
+            '--label', MANAGED_LABEL,
+            '--restart', 'unless-stopped',
+            '--network', resources.network,
+            '--publish', `127.0.0.1:${preview.generated.port}:5900`,
+            '--env-file', preview.generated.environmentPath,
+            '--volume', `${resources.serverDataVolume}:/var/lib/aops`,
+            preview.generated.image,
+        ], 'server_create');
+        created.push({ kind: 'container', name: resources.serverContainer });
+        steps.push({ id: 'server', status: 'completed' });
+        await waitFor(180_000, sleep, () => (dependencies.healthProbe ?? probeHealth)(preview.generated.origin), 'setup_docker_health_timeout');
+        steps.push({ id: 'migrations-health', status: 'completed' });
+        return Object.freeze({
+            schemaVersion: 1,
+            command: 'setup.docker.apply',
+            status: 'installed',
+            method: 'docker-managed',
+            instance: preview.generated.instance,
+            image: preview.generated.image,
+            origin: preview.generated.origin,
+            environmentPath: preview.generated.environmentPath,
+            resources: preview.generated.resources,
+            steps: Object.freeze(steps),
+        });
+    }
+    catch (error) {
+        for (const resource of [...created].reverse()) {
+            if (resource.kind === 'container')
+                runDocker(['container', 'rm', '--force', resource.name]);
+            else if (resource.kind === 'volume')
+                runDocker(['volume', 'rm', '--force', resource.name]);
+            else
+                runDocker(['network', 'rm', resource.name]);
+        }
+        if (environmentWritten)
+            removeEnvironment(preview.generated.environmentPath);
+        throw error;
+    }
+}
+export async function inspectDockerServerSetupStatus(options = {}, dependencies = {}) {
+    const identity = dockerSetupIdentity(options, dependencies);
+    const runDocker = dependencies.runDocker ?? runDockerDefault;
+    const environmentPresent = (dependencies.pathExists ?? existsSync)(identity.environmentPath);
+    const daemon = runDocker(['info', '--format', '{{json .ServerVersion}}']);
+    if (daemon.status !== 0) {
+        const status = environmentPresent ? 'blocked' : 'absent';
+        return Object.freeze({
+            schemaVersion: 1,
+            command: 'setup.docker.status',
+            mutationFree: true,
+            status,
+            method: 'docker-managed',
+            instance: identity.instance,
+            origin: identity.origin,
+            environmentPath: identity.environmentPath,
+            resources: identity.resources,
+            components: Object.freeze({
+                server: Object.freeze({ state: 'unknown', owned: false }),
+                database: Object.freeze({ state: 'unknown', owned: false }),
+                network: Object.freeze({ state: 'unknown', owned: false }),
+                serverData: Object.freeze({ state: 'unknown', owned: false }),
+                databaseData: Object.freeze({ state: 'unknown', owned: false }),
+                environment: Object.freeze({ state: environmentPresent ? 'present' : 'absent' }),
+            }),
+            health: 'not-checked',
+            actions: Object.freeze({ start: false, stop: false, restart: false, openCockpit: false, repair: false }),
+            nextAction: environmentPresent
+                ? 'Start Docker Desktop, then refresh.'
+                : 'Choose Docker setup to install AOPS.',
+        });
+    }
+    const observed = Object.freeze({
+        server: inspectDockerResource(runDocker, 'container', identity.resources.serverContainer),
+        database: inspectDockerResource(runDocker, 'container', identity.resources.postgresContainer),
+        network: inspectDockerResource(runDocker, 'network', identity.resources.network),
+        serverData: inspectDockerResource(runDocker, 'volume', identity.resources.serverDataVolume),
+        databaseData: inspectDockerResource(runDocker, 'volume', identity.resources.postgresDataVolume),
+    });
+    const resources = Object.values(observed);
+    const anyPresent = resources.some((resource) => resource.present);
+    const allPresent = resources.every((resource) => resource.present);
+    const allInspectable = resources.every((resource) => resource.inspectable);
+    const allOwned = resources.filter((resource) => resource.present).every((resource) => resource.owned);
+    const prefix = [
+        observed.network.present,
+        observed.serverData.present,
+        observed.databaseData.present,
+        observed.database.present,
+        observed.server.present,
+    ];
+    const validInterruptedPrefix = prefix.every((present, index) => present || prefix.slice(index + 1).every((later) => !later));
+    const complete = allPresent && environmentPresent && allInspectable && allOwned;
+    const containersRunning = observed.server.state === 'running' && observed.database.state === 'running';
+    const containersStopped = ['created', 'exited'].includes(observed.server.state)
+        && ['created', 'exited'].includes(observed.database.state);
+    const health = containersRunning
+        ? (await (dependencies.healthProbe ?? probeHealth)(identity.origin) ? 'healthy' : 'unreachable')
+        : 'not-checked';
+    let status;
+    let nextAction;
+    if (!anyPresent && !environmentPresent) {
+        status = 'absent';
+        nextAction = 'Choose Docker setup to install AOPS.';
+    }
+    else if (!allInspectable || !allOwned) {
+        status = 'blocked';
+        nextAction = 'These Docker resources are not safely owned by this AOPS installation.';
+    }
+    else if (!complete) {
+        status = environmentPresent && validInterruptedPrefix ? 'repair-required' : 'blocked';
+        nextAction = status === 'repair-required'
+            ? 'Setup was interrupted. Choose Repair setup to continue without deleting database data.'
+            : 'The installation layout is incomplete and cannot be repaired automatically.';
+    }
+    else if (containersRunning && health === 'healthy') {
+        status = 'ready';
+        nextAction = null;
+    }
+    else if (containersStopped) {
+        status = 'stopped';
+        nextAction = 'Choose Start AOPS.';
+    }
+    else {
+        status = 'attention';
+        nextAction = 'Choose Restart AOPS, then refresh.';
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        command: 'setup.docker.status',
+        mutationFree: true,
+        status,
+        method: 'docker-managed',
+        instance: identity.instance,
+        origin: identity.origin,
+        environmentPath: identity.environmentPath,
+        resources: identity.resources,
+        components: Object.freeze({
+            server: Object.freeze({ state: observed.server.state, owned: observed.server.owned }),
+            database: Object.freeze({ state: observed.database.state, owned: observed.database.owned }),
+            network: Object.freeze({ state: observed.network.state, owned: observed.network.owned }),
+            serverData: Object.freeze({ state: observed.serverData.state, owned: observed.serverData.owned }),
+            databaseData: Object.freeze({ state: observed.databaseData.state, owned: observed.databaseData.owned }),
+            environment: Object.freeze({ state: environmentPresent ? 'present' : 'absent' }),
+        }),
+        health,
+        actions: Object.freeze({
+            start: complete && status === 'stopped',
+            stop: complete && (observed.server.state === 'running' || observed.database.state === 'running'),
+            restart: complete,
+            openCockpit: status === 'ready',
+            repair: status === 'repair-required',
+        }),
+        nextAction,
+    });
+}
+function ensureRepairImage(identity, dependencies, runDocker) {
+    let checked = imageCheck(runDocker, identity.image, (dependencies.resolveServerVersion ?? readServerVersion)(), normalizeArchitecture(dependencies.arch ?? process.arch), identity.pullImage);
+    if (checked.status === 'info') {
+        runDockerRequired(runDocker, ['pull', identity.pullImage], 'image_pull');
+        runDockerRequired(runDocker, ['image', 'tag', identity.pullImage, identity.image], 'image_tag');
+        checked = imageCheck(runDocker, identity.image, (dependencies.resolveServerVersion ?? readServerVersion)(), normalizeArchitecture(dependencies.arch ?? process.arch), identity.pullImage);
+    }
+    if (checked.status !== 'pass')
+        throw new Error('setup_docker_image_contract_invalid');
+}
+export async function runDockerServerLifecycle(action, options = {}, dependencies = {}) {
+    const before = await inspectDockerServerSetupStatus(options, dependencies);
+    const allowed = action === 'start' ? before.actions.start
+        : action === 'stop' ? before.actions.stop
+            : action === 'restart' ? before.actions.restart
+                : action === 'open-cockpit' ? before.actions.openCockpit
+                    : before.actions.repair;
+    if (!allowed)
+        throw new Error(`setup_docker_${action}_not_available:${before.status}`);
+    if (action === 'open-cockpit') {
+        await (dependencies.openUrl ?? openExternalUrl)(before.origin);
+        return Object.freeze({
+            schemaVersion: 1,
+            command: 'setup.docker.lifecycle',
+            status: 'completed',
+            action,
+            changed: false,
+            instance: before.instance,
+            origin: before.origin,
+            after: before,
+        });
+    }
+    const identity = dockerSetupIdentity(options, dependencies);
+    const runDocker = dependencies.runDocker ?? runDockerDefault;
+    const sleep = dependencies.sleep ?? delay;
+    let changed = false;
+    const waitForDatabase = () => waitFor(90_000, sleep, () => {
+        const result = runDocker([
+            'exec', identity.resources.postgresContainer,
+            'pg_isready', '-U', 'aops', '-d', 'aops',
+        ]);
+        return result.status === 0;
+    }, 'setup_docker_postgres_timeout');
+    const waitForHealth = () => waitFor(180_000, sleep, () => (dependencies.healthProbe ?? probeHealth)(identity.origin), 'setup_docker_health_timeout');
+    if (action === 'repair') {
+        ensureRepairImage(identity, dependencies, runDocker);
+        if (before.components.network.state === 'absent') {
+            runDockerRequired(runDocker, ['network', 'create', '--label', MANAGED_LABEL, identity.resources.network], 'network_create');
+            changed = true;
+        }
+        for (const [state, name] of [
+            [before.components.serverData.state, identity.resources.serverDataVolume],
+            [before.components.databaseData.state, identity.resources.postgresDataVolume],
+        ]) {
+            if (state === 'absent') {
+                runDockerRequired(runDocker, ['volume', 'create', '--label', MANAGED_LABEL, name], 'volume_create');
+                changed = true;
+            }
+        }
+        if (before.components.database.state === 'absent') {
+            runDockerRequired(runDocker, [
+                'run', '--detach', '--name', identity.resources.postgresContainer,
+                '--label', MANAGED_LABEL,
+                '--restart', 'unless-stopped',
+                '--network', identity.resources.network,
+                '--network-alias', 'postgres',
+                '--env-file', identity.environmentPath,
+                '--volume', `${identity.resources.postgresDataVolume}:/var/lib/postgresql/data`,
+                POSTGRES_IMAGE,
+            ], 'postgres_create');
+            changed = true;
+        }
+        else if (before.components.database.state !== 'running') {
+            runDockerRequired(runDocker, ['start', identity.resources.postgresContainer], 'postgres_start');
+            changed = true;
+        }
+        await waitForDatabase();
+        if (before.components.server.state === 'absent') {
+            runDockerRequired(runDocker, [
+                'run', '--detach', '--name', identity.resources.serverContainer,
+                '--label', MANAGED_LABEL,
+                '--restart', 'unless-stopped',
+                '--network', identity.resources.network,
+                '--publish', `127.0.0.1:${identity.port}:5900`,
+                '--env-file', identity.environmentPath,
+                '--volume', `${identity.resources.serverDataVolume}:/var/lib/aops`,
+                identity.image,
+            ], 'server_create');
+            changed = true;
+        }
+        else if (before.components.server.state !== 'running') {
+            runDockerRequired(runDocker, ['start', identity.resources.serverContainer], 'server_start');
+            changed = true;
+        }
+        await waitForHealth();
+    }
+    else if (action === 'stop') {
+        if (before.components.server.state === 'running') {
+            runDockerRequired(runDocker, ['stop', identity.resources.serverContainer], 'server_stop');
+            changed = true;
+        }
+        if (before.components.database.state === 'running') {
+            runDockerRequired(runDocker, ['stop', identity.resources.postgresContainer], 'postgres_stop');
+            changed = true;
+        }
+    }
+    else if (action === 'start') {
+        if (before.components.database.state !== 'running') {
+            runDockerRequired(runDocker, ['start', identity.resources.postgresContainer], 'postgres_start');
+            changed = true;
+        }
+        await waitForDatabase();
+        if (before.components.server.state !== 'running') {
+            runDockerRequired(runDocker, ['start', identity.resources.serverContainer], 'server_start');
+            changed = true;
+        }
+        await waitForHealth();
+    }
+    else {
+        runDockerRequired(runDocker, ['restart', identity.resources.postgresContainer], 'postgres_restart');
+        await waitForDatabase();
+        runDockerRequired(runDocker, ['restart', identity.resources.serverContainer], 'server_restart');
+        await waitForHealth();
+        changed = true;
+    }
+    const after = await inspectDockerServerSetupStatus(options, dependencies);
+    return Object.freeze({
+        schemaVersion: 1,
+        command: 'setup.docker.lifecycle',
+        status: 'completed',
+        action,
+        changed,
+        instance: after.instance,
+        origin: after.origin,
+        after,
+    });
+}