@wtfalch/foundry 0.42.1 → 0.43.0

package/dist/plan/blue-green.js

@@ -0,0 +1,444 @@
+import { createHash } from 'node:crypto';
+import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
+import { serverConnectorScopeKey } from './cloudflared-connector.js';
+import { entryHostnames, tunnelIngressHostnames, wildcardHostname } from './hostnames.js';
+import { appNameFor, appStepKey } from './platform-diff.js';
+import { remoteDatabaseAppliedFor } from './remote-database.js';
+export const COLORS = ['blue', 'green'];
+/** The name of `base`'s copy in `color`: `<base>-blue`. */
+export function colorAppName(base, color) {
+    return `${base}-${color}`;
+}
+export const lbAppName = (base) => `${base}-lb`;
+export const stageAppName = (base) => `${base}-stage`;
+/** The color a name carries, or `null`. */
+export function colorOfName(name) {
+    return COLORS.find((color) => name.endsWith(`-${color}`)) ?? null;
+}
+/** Live blue until a release moves it. */
+export const DEFAULT_WEIGHTS = 'blue:100,green:0';
+/** `blue:95,green:5`. Whole percentages that sum to 100, so a typo cannot send traffic nowhere. */
+export function parseWeights(raw) {
+    const text = raw ?? DEFAULT_WEIGHTS;
+    const match = /^blue:(\d{1,3}),green:(\d{1,3})$/.exec(text);
+    if (!match)
+        return null;
+    const weights = { blue: Number(match[1]), green: Number(match[2]) };
+    return weights.blue + weights.green === 100 ? weights : null;
+}
+export const formatWeights = (w) => `blue:${w.blue},green:${w.green}`;
+/** The scope keys of a blue/green subject (contract C3). `.` separated, no `:`. */
+export const bgKey = {
+    live: (id) => `bg.${id}.live`,
+    digest: (id, color) => `bg.${id}.digest.${color}`,
+    weights: (id) => `bg.${id}.weights`,
+    stage: (id) => `bg.${id}.stage`,
+    window: (id) => `bg.${id}.window`,
+    held: (id, digest) => `bg.${id}.held.${digest}`,
+    /** The weights the load balancer on `server` was last written with. */
+    lb: (id, server) => `bg.${id}.lb.${server}`,
+    /** The hash of the structure (apps, balancer, stage) last applied on `server`. */
+    applied: (id, server) => `bg.${id}.applied.${server}`,
+    /** The Coolify app of one part (`blue`, `green`, `lb`, `stage`) on `server`. */
+    app: (id, server, part) => `bg.${id}.app.${server}.${part}`,
+    /** The cloudflared connector app of the tunnel on a non-primary `server`. */
+    connector: (id, server) => `bg.${id}.connector.${server}`,
+    stageDatabase: (id) => `bg.${id}.stagedb`,
+    /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
+    blueName: (id) => `bg.${id}.bluename`,
+    /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
+    pinKey: (id) => `bg.${id}.pinkey`,
+};
+/** The three env names the reporting health read uses (contract C1). */
+export const REPORTING_ENV = {
+    color: 'REPORTING_COLOR',
+    release: 'REPORTING_RELEASE',
+    healthToken: 'REPORTING_HEALTH_TOKEN',
+};
+/** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
+export const healthTokenName = (id) => `reporting-health-${id}`;
+/** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
+export function reportingEnv(input) {
+    return [
+        { key: REPORTING_ENV.color, value: input.color },
+        ...(input.release ? [{ key: REPORTING_ENV.release, value: input.release }] : []),
+        { key: REPORTING_ENV.healthToken, value: input.healthToken },
+    ];
+}
+/**
+ * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
+ * `recorded` names the blue app: an app that ran before blue/green keeps its own name (see {@link liveAppNameFor}).
+ */
+export function entrySubject(org, entry, recorded) {
+    if (!entry.blueGreen || entry.repo === null || !org.hosting.enabled)
+        return null;
+    const base = appNameFor(org, entry);
+    const isStatic = entry.buildPack === 'static';
+    return {
+        id: entry.key,
+        base,
+        primaryBlueName: liveAppNameFor(org, entry, recorded),
+        port: isStatic ? 80 : (entry.port ?? 80),
+        repo: entry.repo,
+        folder: entry.folder,
+        branch: entry.branch,
+        buildPack: entry.buildPack,
+        healthPath: entry.healthPath ?? (isStatic ? '/' : '/api/health'),
+        database: entry.database,
+        hostnames: entryHostnames(org, entry),
+        config: entry.blueGreen,
+    };
+}
+/**
+ * The Coolify name of the entry's app on the primary. A blue/green entry's app is its blue copy: the recorded
+ * name; else the entry's own name when its app is already recorded (it ran before blue/green and is adopted as
+ * blue, never renamed); else `<base>-blue` for an entry with no app yet.
+ */
+export function liveAppNameFor(org, entry, recorded = {}) {
+    const base = appNameFor(org, entry);
+    if (!entry.blueGreen)
+        return base;
+    const named = recorded[bgKey.blueName(entry.key)];
+    if (named)
+        return named;
+    return recorded[`coolify:app:${appStepKey(org, entry.key)}`] ? base : colorAppName(base, 'blue');
+}
+/** Whether the balancer on the primary is written and the structure applied: the tunnel may move to it. */
+export function balancerApplied(id, recorded, primaryUuid) {
+    return Boolean(primaryUuid && recorded[bgKey.lb(id, primaryUuid)] && recorded[bgKey.applied(id, primaryUuid)]);
+}
+/** The origin the tunnel routes a subject's names to: its balancer, reached on each server's own network. */
+export function lbOrigin(subject) {
+    return `http://${lbAppName(subject.base)}:${subject.port}`;
+}
+/** Usable and reachable servers in the order Coolify lists them, and the uuids of the rest. */
+export function splitServers(all) {
+    const up = [];
+    const down = [];
+    for (const server of all)
+        (server.usable && server.reachable ? up : down).push(server.uuid);
+    return { up, down };
+}
+/** The scope key of the org's primary server (`COOLIFY_SERVER_SCOPE_KEY` in `executor.ts`). */
+export const PRIMARY_SERVER_SCOPE_KEY = 'coolify_server';
+// ---- the load balancer -----------------------------------------------------
+/** The sticky cookie that keeps a user on one color. */
+export const LB_COOKIE_NAME = 'bg_color';
+/** A request with this header goes to the named color whatever the weights; the release runner checks a color with it. */
+export const LB_COLOR_HEADER = 'X-Foundry-Color';
+/** A pinned request also carries this header with the entry's pin key, so a stranger cannot pin a color. */
+export const LB_PIN_HEADER = 'X-Foundry-Pin';
+const PIN_KEY = /^[0-9a-f]{64}$/;
+/** Above the default priority of `app` (its rule length), so a pinned request never reaches the weighted service. */
+const LB_PIN_PRIORITY = 10000;
+export const LB_CONFIG_PATH = '/etc/traefik/dynamic/lb.yml';
+/** Where the balancer's config lives inside the container, mounted as one file. */
+const LB_ENTRYPOINT = 'web';
+/**
+ * The balancer's inline Dockerfile: a pinned Traefik with a file provider watching one directory.
+ * Weights are never in here, so a weight change is a config write and never a redeploy.
+ */
+export function lbDockerfile(port) {
+    return [
+        `FROM traefik:${pinnedRef('traefik')}`,
+        `CMD ["--providers.file.directory=/etc/traefik/dynamic", "--providers.file.watch=true", "--entrypoints.${LB_ENTRYPOINT}.address=:${port}", "--entrypoints.traefik.address=:8080", "--ping=true", "--log.level=WARN", "--accesslog=false", "--api=false"]`,
+        'HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 CMD ["traefik", "healthcheck", "--ping"]',
+        '',
+    ].join('\n');
+}
+/** The traefik tag the balancer runs, for a test that keeps the pin and the Dockerfile equal. */
+export const LB_IMAGE_REF = `traefik:${VERSIONS.traefik}`;
+/**
+ * The balancer's dynamic config: two weighted services and a sticky cookie. A color at weight 0 is left out
+ * of the weighted list, because Traefik sends a request that carries a sticky cookie to the named service
+ * whatever its weight, which would keep a rolled-back user on the failed color. The weights are in the first
+ * line, so a reader sees both numbers. `backends` are the URLs of each color's containers, one per server.
+ */
+export function renderLbConfig(input) {
+    const { weights, backends, pinKey } = input;
+    if (!PIN_KEY.test(pinKey))
+        throw new Error('the load balancer pin key is not 64 hex characters');
+    const listed = COLORS.filter((color) => weights[color] > 0);
+    const lines = [
+        `# weights ${formatWeights(weights)}`,
+        'http:',
+        '  routers:',
+        ...COLORS.flatMap((color) => [
+            `    pin-${color}:`,
+            `      rule: Header(\`${LB_COLOR_HEADER}\`, \`${color}\`) && Header(\`${LB_PIN_HEADER}\`, \`${pinKey}\`)`,
+            `      priority: ${LB_PIN_PRIORITY}`,
+            `      entryPoints: [${LB_ENTRYPOINT}]`,
+            `      service: ${color}`,
+        ]),
+        '    app:',
+        '      rule: PathPrefix(`/`)',
+        `      entryPoints: [${LB_ENTRYPOINT}]`,
+        '      service: weighted',
+        '  services:',
+        '    weighted:',
+        '      weighted:',
+        '        sticky:',
+        '          cookie:',
+        `            name: ${LB_COOKIE_NAME}`,
+        '            httpOnly: true',
+        '            secure: true',
+        '            sameSite: lax',
+        '        services:',
+        ...listed.flatMap((color) => [
+            `          - name: ${color}`,
+            `            weight: ${weights[color]}`,
+        ]),
+    ];
+    for (const color of COLORS) {
+        lines.push(`    ${color}:`, '      loadBalancer:', '        servers:', ...backends[color].map((url) => `          - url: ${url}`));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * The URL of one color's container on its own server's network. On the primary, blue is the app that was
+ * already there, under its own name; every other color is `<base>-<color>`.
+ */
+export const colorBackend = (subject, color, onPrimary) => `http://${onPrimary && color === 'blue' ? subject.primaryBlueName : colorAppName(subject.base, color)}:${subject.port}`;
+/** A short hash of what decides the shape of a server's apps, so a change replans the server. */
+export function structureHash(subject, input) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        base: subject.base,
+        port: subject.port,
+        repo: subject.repo,
+        folder: subject.folder,
+        branch: subject.branch,
+        buildPack: subject.buildPack,
+        healthPath: subject.healthPath,
+        database: subject.database,
+        primary: input.primary,
+        lb: VERSIONS.traefik,
+    }))
+        .digest('hex')
+        .slice(0, 16);
+}
+/** Hostnames of the tunnel that no blue/green entry serves; a connector on a second server cannot answer them. */
+export function namesNotBlueGreen(org) {
+    const served = new Set();
+    for (const entry of org.hosting.entries) {
+        if (!entry.blueGreen)
+            continue;
+        for (const name of entryHostnames(org, entry))
+            served.add(name);
+        if (entry.hostnames.includes('*')) {
+            const wildcard = wildcardHostname(org);
+            if (wildcard)
+                served.add(wildcard);
+        }
+    }
+    return tunnelIngressHostnames(org).filter((name) => !served.has(name));
+}
+const MAX_NAME = 63;
+/** Restated from `executor.ts`, the same rule as `diff.ts` does: the app id of the org tunnel's cloudflared connector. */
+const TUNNEL_CONNECTOR_APP_SCOPE_KEY = 'cloudflare_tunnel_connector_app';
+/**
+ * Plans the blue/green parts of an org: per usable server, one structure step (the apps, the balancer, the
+ * stage on the primary) when the recorded shape differs, else one balancer-config step when only the weights
+ * differ. A server that is down is skipped and reported in `unmanaged`. Pure: reads nothing but its input.
+ */
+export function planBlueGreen(input) {
+    const { org, recordedIds } = input;
+    const steps = [];
+    const unmanaged = [];
+    for (const entry of org.hosting.entries) {
+        const subject = entrySubject(org, entry, recordedIds);
+        if (!subject)
+            continue;
+        const id = subject.id;
+        const blocked = (why, part = 'blocked') => unmanaged.push({
+            description: `${org.slug}'s ${id} app blue/green is blocked, not planned: ${why}`,
+            key: `bg:${id}:${part}`,
+        });
+        if (entry.buildPack === 'dockercompose')
+            continue;
+        if (colorAppName(subject.base, 'green').length > MAX_NAME) {
+            blocked('its app name is too long for the green copy; shorten the slug or the entry key');
+            continue;
+        }
+        if (!input.servers) {
+            blocked('the host cannot list Coolify servers');
+            continue;
+        }
+        if (!input.canHoldSecrets) {
+            blocked('the host cannot hold the health token (its held keys cannot put)');
+            continue;
+        }
+        const weights = parseWeights(recordedIds[bgKey.weights(id)]);
+        if (!weights) {
+            blocked(`the recorded weights are not 'blue:<n>,green:<n>' summing to 100`, 'weights');
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${appStepKey(org, id)}`] && !input.appPlanned(id)) {
+            blocked('its blue copy is not recorded and no app step is planned to make it');
+            continue;
+        }
+        const { up, down } = splitServers(input.servers);
+        const recordedPrimary = recordedIds[PRIMARY_SERVER_SCOPE_KEY];
+        const primary = recordedPrimary ?? up[0];
+        if (!primary || !up.includes(primary)) {
+            blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
+            continue;
+        }
+        for (const uuid of down) {
+            unmanaged.push({
+                description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${uuid}: the server is not usable or not reachable right now`,
+                key: `bg:${id}:down:${uuid}`,
+            });
+        }
+        const others = up.filter((uuid) => uuid !== primary);
+        const unrouted = namesNotBlueGreen(org);
+        const useOthers = others.length > 0 && unrouted.length === 0;
+        if (others.length > 0 && !useOthers) {
+            blocked('a second server needs every name on the tunnel to be blue/green, because its connector answers all of them', 'servers');
+        }
+        const targets = [primary, ...(useOthers ? others : [])];
+        if (useOthers && recordedIds[`cloudflare:tunnel:${org.id}`]) {
+            for (const server of others) {
+                const key = `${org.id}:${server}`;
+                if (!recordedIds[serverConnectorScopeKey(TUNNEL_CONNECTOR_APP_SCOPE_KEY, server)] &&
+                    !steps.some((s) => s.kind === 'bluegreen-connector' && s.key === key)) {
+                    steps.push({
+                        kind: 'bluegreen-connector',
+                        phase: 'after',
+                        key,
+                        description: `run a cloudflared connector for ${org.slug}'s Cloudflare tunnel on Coolify server ${server}`,
+                        desired: { server, primary },
+                    });
+                }
+            }
+        }
+        for (const server of targets) {
+            const isPrimary = server === primary;
+            const key = `${org.id}:${id}:${server}`;
+            const hash = structureHash(subject, { primary: isPrimary });
+            if (!isPrimary && subject.database && !remoteDatabaseAppliedFor(recordedIds, id, server)) {
+                unmanaged.push({
+                    description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${server} yet: its database route to that server is not applied`,
+                    key: `bg:${id}:dbroute:${server}`,
+                });
+                continue;
+            }
+            if (recordedIds[bgKey.applied(id, server)] !== hash) {
+                steps.push({
+                    kind: 'bluegreen',
+                    phase: 'before',
+                    key,
+                    description: `run ${org.slug}'s ${id} app as blue and green behind a load balancer on Coolify server ${server}${isPrimary ? ', with a stage copy' : ''}`,
+                    desired: { entry: id, server, primary, weights: formatWeights(weights) },
+                });
+            }
+            else if (recordedIds[bgKey.lb(id, server)] !== formatWeights(weights)) {
+                steps.push({
+                    kind: 'bluegreen-lb',
+                    phase: 'before',
+                    key,
+                    description: `set ${org.slug}'s ${id} app traffic to ${formatWeights(weights)} on Coolify server ${server}`,
+                    desired: { entry: id, server, primary, weights: formatWeights(weights) },
+                });
+            }
+        }
+    }
+    return { steps, unmanaged };
+}
+// ---- platform-archon -------------------------------------------------------
+/** The scope-key id, base name and port platform-archon runs under. */
+export const ARCHON_SUBJECT_ID = 'platform-archon';
+/** https://github.com/wtfalch/archon: one Dockerfile at its root, `runner` stage on port 3000. */
+export const ARCHON_REPO = 'wtfalch/archon';
+const ARCHON_PORT_NUMBER = 3000;
+/**
+ * platform-archon as a blue/green subject: the same type a hosting entry makes. Its running app keeps its
+ * name and serves as the blue copy, because renaming its container would take its sign-in and tunnel down
+ * mid-apply; green and the balancer are new apps beside it.
+ */
+export function archonSubject(platform, repo) {
+    const { archon } = platform;
+    if (!archon.enabled || !archon.blueGreen)
+        return null;
+    return {
+        id: ARCHON_SUBJECT_ID,
+        base: ARCHON_SUBJECT_ID,
+        primaryBlueName: ARCHON_SUBJECT_ID,
+        port: ARCHON_PORT_NUMBER,
+        repo,
+        folder: null,
+        branch: archon.gitRef,
+        buildPack: 'dockerfile',
+        healthPath: '/api/health',
+        database: true,
+        hostnames: [archon.hostname],
+        config: archon.blueGreen,
+    };
+}
+/**
+ * Where the tunnel sends a subject's names: its balancer once the structure on the primary is applied (the
+ * balancer's config written and every part running), else the app as before. Pointing the tunnel at a balancer
+ * that does not exist or does not answer yet would take the site down.
+ */
+export function tunnelOriginFor(subject, recorded, primaryUuid, fallback) {
+    if (!subject || !balancerApplied(subject.id, recorded, primaryUuid))
+        return fallback;
+    return lbOrigin(subject);
+}
+/** The origin the archon step last wrote to the tunnel through {@link tunnelOriginFor}, recorded by the platform step. */
+export const ARCHON_BG_ORIGIN_SCOPE_KEY = 'archon_bluegreen_origin';
+/** The platform scope keys the archon plan reads (restated from `platform-diff.ts`, which imports this module). */
+const ARCHON_APP_RECORD = 'coolify:app:platform:archon';
+const ARCHON_TUNNEL_RECORD = 'cloudflare_platform_archon_tunnel';
+/**
+ * Plans the one platform step that runs platform-archon on the blue/green path: the structure on the primary
+ * server, the balancer's weights, and the tunnel's move to the balancer. It plans nothing until archon's app and
+ * tunnel are recorded, because the step copies the app's env and moves that tunnel. Archon runs on the primary
+ * only: the platform has no database route to another server.
+ */
+export function planArchonBlueGreen(input) {
+    const subject = archonSubject(input.platform, input.repo);
+    const none = { step: null, unmanaged: [] };
+    if (!subject)
+        return none;
+    const { recorded } = input;
+    if (!recorded[ARCHON_APP_RECORD] || !recorded[ARCHON_TUNNEL_RECORD])
+        return none;
+    const blocked = (why) => ({
+        step: null,
+        unmanaged: [
+            {
+                description: `platform-archon blue/green is blocked, not planned: ${why}`,
+                key: `bg:${subject.id}:blocked`,
+            },
+        ],
+    });
+    if (input.executorBlocked)
+        return blocked(input.executorBlocked);
+    if (!input.servers)
+        return blocked('the host cannot list Coolify servers');
+    const weights = parseWeights(recorded[bgKey.weights(subject.id)]);
+    if (!weights)
+        return blocked(`the recorded weights are not 'blue:<n>,green:<n>' summing to 100`);
+    const { up } = splitServers(input.servers);
+    const primary = recorded[PRIMARY_SERVER_SCOPE_KEY] ?? up[0];
+    if (!primary || !up.includes(primary)) {
+        return blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
+    }
+    const done = recorded[bgKey.applied(subject.id, primary)] === structureHash(subject, { primary: true }) &&
+        recorded[bgKey.lb(subject.id, primary)] === formatWeights(weights) &&
+        recorded[ARCHON_BG_ORIGIN_SCOPE_KEY] === lbOrigin(subject);
+    if (done)
+        return none;
+    return {
+        unmanaged: [],
+        step: {
+            kind: 'bluegreen',
+            phase: 'after',
+            key: subject.id,
+            description: `run platform-archon as blue and green behind a load balancer on Coolify server ${primary}, then send its tunnel to the balancer`,
+            desired: { subject: subject.id, primary, weights: formatWeights(weights) },
+        },
+    };
+}

package/dist/plan/cloudflared-connector.d.ts

@@ -76,3 +76,29 @@ export declare function ensureCloudflaredConnector(input: EnsureCloudflaredConne
     appId: string;
     deployed: boolean;
 }>;
+/** The scope key of a non-primary server's connector: the tunnel's own key plus the server uuid. */
+export declare function serverConnectorScopeKey(baseScopeKey: string, serverUuid: string): string;
+/** A non-primary server's connector app name: the tunnel's own name plus the first eight characters of the uuid. */
+export declare function serverConnectorAppName(baseAppName: string, serverUuid: string): string;
+export interface EnsureConnectorsOnServersInput extends Omit<EnsureCloudflaredConnectorInput, 'resolveServer' | 'recordedConnectorAppId' | 'recordAppId' | 'appName'> {
+    /** The primary's connector keeps its name and scope key, so a record made before servers were many is still its record. */
+    baseAppName: string;
+    baseScopeKey: string;
+    primaryUuid: string;
+    serverUuids: readonly string[];
+    recorded: Readonly<Record<string, string>>;
+    /** Records the app id as soon as it exists; the caller persists it. */
+    record: (key: string, appId: string) => Promise<void>;
+}
+/**
+ * One connector app for the tunnel on each server, all with the tunnel's one token. Each server's connector
+ * reaches that server's own containers, so a request lands on a server with the app on it. The primary's
+ * connector is the existing one (found by its recorded id, never created again); every other server gets its
+ * own name and scope key. A failure on one server stops the loop there: the ones before it are recorded,
+ * and the next run repeats from the failed one.
+ */
+export declare function ensureConnectorsOnServers(input: EnsureConnectorsOnServersInput): Promise<Array<{
+    serverUuid: string;
+    appId: string;
+    deployed: boolean;
+}>>;

package/dist/plan/cloudflared-connector.js

@@ -119,3 +119,40 @@ async function tunnelTokenDiffers(coolify, appId, token) {
     const live = (await coolify.listEnvs(appId)).find((e) => e.key === 'TUNNEL_TOKEN' && !e.is_preview);
     return !live || live.value !== token;
 }
+/** The scope key of a non-primary server's connector: the tunnel's own key plus the server uuid. */
+export function serverConnectorScopeKey(baseScopeKey, serverUuid) {
+    return `${baseScopeKey}.${serverUuid}`;
+}
+/** A non-primary server's connector app name: the tunnel's own name plus the first eight characters of the uuid. */
+export function serverConnectorAppName(baseAppName, serverUuid) {
+    return `${baseAppName}-${serverUuid.slice(0, 8)}`;
+}
+/**
+ * One connector app for the tunnel on each server, all with the tunnel's one token. Each server's connector
+ * reaches that server's own containers, so a request lands on a server with the app on it. The primary's
+ * connector is the existing one (found by its recorded id, never created again); every other server gets its
+ * own name and scope key. A failure on one server stops the loop there: the ones before it are recorded,
+ * and the next run repeats from the failed one.
+ */
+export async function ensureConnectorsOnServers(input) {
+    const results = [];
+    for (const serverUuid of input.serverUuids) {
+        const primary = serverUuid === input.primaryUuid;
+        const scopeKey = primary
+            ? input.baseScopeKey
+            : serverConnectorScopeKey(input.baseScopeKey, serverUuid);
+        const { appId, deployed } = await ensureCloudflaredConnector({
+            coolify: input.coolify,
+            tunnels: input.tunnels,
+            tunnelId: input.tunnelId,
+            projectUuid: input.projectUuid,
+            environment: input.environment,
+            appName: primary ? input.baseAppName : serverConnectorAppName(input.baseAppName, serverUuid),
+            resolveServer: async () => ({ uuid: serverUuid }),
+            recordedConnectorAppId: input.recorded[scopeKey] ?? null,
+            recordAppId: (appId) => input.record(scopeKey, appId),
+        });
+        results.push({ serverUuid, appId, deployed });
+    }
+    return results;
+}

package/dist/plan/diff.d.ts

@@ -1,8 +1,10 @@
 import type { DeclaredOrg, OrgId, OrgServiceSchema } from '../org.js';
 import type { Plan, PlanStep, UnmanagedItem, VersionChangeItem } from '../plan.js';
 import { type AgoraHostReading } from './agora.js';
+import { type BlueGreenServer } from './blue-green.js';
 import type { LiveResource } from './live.js';
 import { type OrgPlatformReadiness } from './platform-org.js';
+import { type RemoteDatabaseFacts } from './remote-database.js';
 /**
  * What a {@link StepExecutor} (see `plan-apply.ts`) needs to actually make a
  * step true, alongside the public {@link PlanStep} an operator reads.
@@ -41,6 +43,8 @@ export interface DraftStep {
  * New ones go here, not in new positional arguments (rule 7).
  */
 export interface PlanOrgOptions {
+    /** What the blue/green database route needs (`plan/remote-database.ts`). Absent: nothing is planned. */
+    remoteDatabase?: RemoteDatabaseFacts;
     /** The platform's edge has the `oikos.host` zone: a company without a domain waits on it for its own services. */
     oikosZoneReady?: boolean;
     /** #267: the executor was built with a `loginHostBindings` port. */
@@ -108,6 +112,8 @@ export interface PlanOrgOptions {
      * but the storage is not registered, so each database is reported blocked.
      */
     backupStorageUuid?: string | null;
+    /** Every Coolify server the host lists, for blue/green (`plan/blue-green.ts`). Absent: the host cannot list them. */
+    blueGreenServers?: readonly BlueGreenServer[];
 }
 export interface PlanDetail {
     orgId: OrgId;

package/dist/plan/diff.js

@@ -1,6 +1,7 @@
 import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, heldEnvRef, ownerMailboxRecorded, ownerMailboxes, ownsServices, } from '../org.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, withRecordedMessagingProject, } from './agora.js';
+import { planBlueGreen } from './blue-green.js';
 import { BOULE_BRIDGE_SECRET_ENV, BOULE_BROKER_ENTRY_KEY, BOULE_MAIL_TOKEN_ENV, BOULE_PEER_PASSWORD_ENV, BOULE_SECRETS_RESTARTED_SCOPE_KEY, bouleEnvDrift, bouleMailTokenDrift, bouleMailWanted, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, } from './broker-entries.js';
 import { chatInternalNames, chatUpstreams } from './chat-matrix.js';
@@ -23,6 +24,7 @@ import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_
 import { DEFAULT_ORG_PLATFORM_READINESS, } from './platform-org.js';
 import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY, CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY, appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec, entryOikosHostnames, entryRoutes, entryRoutesMarker, } from './proxy-labels.js';
+import { planRemoteDatabase } from './remote-database.js';
 import { ZITADEL_ORG_DOMAIN_BLOCKED_SCOPE_KEY, ZITADEL_ORG_DOMAIN_SCOPE_KEY, ZITADEL_ORG_REGISTRATION_CLOSED_SCOPE_KEY, signInDomainBlockedText, signInOrgDomain, } from './sign-in-org.js';
 import { SIGN_IN_BASE_PATH, SIGN_IN_IMAGE_TAG_SUFFIX, SIGN_IN_IN_APP_SCOPE_KEY, SIGN_IN_LOGIN_APP_SCOPE_KEY, SIGN_IN_LOGIN_INTERNAL_NAME, SIGN_IN_RATE_LIMIT_SCOPE_KEY, SIGN_IN_TRUSTED_SCOPE_KEY, inAppSignIn, inAppStatePairs, inAppTargets, } from './sign-in.js';
 import { withStepSystem } from './step-system.js';
@@ -456,6 +458,18 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const edgeReservedLabels = planEdgeReservedLabels(org, recordedIds, platformReadiness, options.platformHostnames ?? []);
     if (edgeReservedLabels.step)
         plannedSteps.push(edgeReservedLabels.step);
+    // Blue/green (`blue-green.ts`): the apps and balancers before the tunnel routes to them, a second
+    // server's connector after the tunnel exists.
+    const blueGreen = planBlueGreen({
+        org,
+        recordedIds,
+        servers: options.blueGreenServers,
+        canHoldSecrets: platformReadiness.canHoldSecrets === true,
+        appPlanned: (entryKey) => plannedSteps.some((p) => p.action.system === 'coolify' &&
+            p.action.kind === 'app' &&
+            p.action.key === appStepKey(org, entryKey)),
+    });
+    plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'before').map(blueGreenDraft()));
     const tunnel = planTunnel(org, byKey, claimed, recordedIds, platformReadiness.platformApex);
     // #238: a tunnel that is being provisioned waits for an active zone; parking
     // one never does.
@@ -482,6 +496,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     else if (tunnel) {
         plannedSteps.push(tunnel);
     }
+    plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'after').map(blueGreenDraft()));
     // Right after the zone (#43): `cloudflareRateLimit` resolves the zone by
     // apex domain, so the zone step above must already have run (or the zone
     // must already exist live) by the time this one's action executes.
@@ -549,6 +564,9 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     (jobsAvailable && !ownsServices(org)) || platformReadiness.jobsReady, platformReadiness.missingKeys.jobs, platformReadiness.noKeyReader, platformReadiness.jobsUrlMissing ?? false);
     if (jobsRegistration.step)
         plannedSteps.push(jobsRegistration.step);
+    const remoteDatabase = planRemoteDatabase(org, options.remoteDatabase, recordedIds);
+    if (remoteDatabase.step)
+        plannedSteps.push(remoteDatabase.step);
     // F8 (#318), after Agora and Boule, not right after the zone: a route
     // already bound by a hand-made entry, another entry's route, a taken
     // script name, or no Workers token all throw at apply, and `runSteps`
@@ -615,6 +633,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     // orphan a second live key.
     if (aiKey.blocked)
         unmanaged.push({ description: aiKey.blocked, key: 'ai:key' });
+    unmanaged.push(...blueGreen.unmanaged);
     unmanaged.push(...filesKeys.blocked);
     unmanaged.push(...entryAiKeys.blocked);
     unmanaged.push(...edgeWorkers.blocked);
@@ -644,6 +663,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     if (jobsRegistration.blocked) {
         unmanaged.push({ description: jobsRegistration.blocked, key: 'jobs:registration' });
     }
+    if (remoteDatabase.blocked)
+        unmanaged.push(remoteDatabase.blocked);
     // #177: an org step whose own shared platform service is off or not yet
     // applied is blocked here, not planned -- the same rule, now driven by
     // `platformReadiness` instead of a host-supplied port. Each is reported at
@@ -740,6 +761,13 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         orgPostgres,
     };
 }
+/** A blue/green plan step as the draft step `computePlanDetail` collects. */
+function blueGreenDraft() {
+    return (step) => ({
+        action: { system: 'coolify', kind: step.kind, key: step.key, desired: step.desired },
+        step: { description: step.description, destroys: false, migrates: false },
+    });
+}
 /** Steps that run against the org's own ZITADEL instance (its projects, apps and broker entries). */
 const NEEDS_OWN_ZITADEL = new Set([
     'zitadel:issuer',
@@ -3336,7 +3364,7 @@ function planTunnel(org, byKey, claimed, recordedIds, platformApex) {
         (org.calls.enabled && org.calls.usesDomain && Boolean(org.domain)) ||
         Boolean(org.domain) ||
         // A company without a domain still gets a tunnel of its own for an entry at `<slug>.oikos.host`.
-        entryRoutes(org).length > 0;
+        entryRoutes(org, recordedIds).length > 0;
     const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`, org.id, 
     // Cloudflare's status, read against what is declared: a park cannot change
     // it, so judging on/off by status alone would never let the plan empty.
@@ -3393,7 +3421,8 @@ function planTunnel(org, byKey, claimed, recordedIds, platformApex) {
     // An entry's hostname goes straight to its container, so a changed port, key or name, or an ingress
     // written before entries were routed that way, needs the ingress written again. Nothing recorded
     // equals no routes.
-    const routesStale = (recordedIds[CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY] ?? '[]') !== entryRoutesMarker(org);
+    const routesStale = (recordedIds[CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY] ?? '[]') !==
+        entryRoutesMarker(org, recordedIds);
     if (!connectorMissing && !dnsStale && !routesStale)
         return null;
     return {