@wtfalch/foundry 0.39.4 → 0.39.6

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICE
 export type { FilesHostInput, JobsHostDeps, JobsHostInput, OwnAuthInstance, PlanOwnAuthOptions, PlanOwnFilesOptions, PlanOwnFilesR2Options, PlanOwnJobsOptions, } from './plan/index.js';
 export { OWN_AUTH_APPLIED_GIT_REF_SCOPE_KEY, OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY, OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, provisionFilesHost, provisionJobsHost, provisionMailServer, } from './plan/index.js';
 export type { PlanOwnSfuOptions, SfuAppDeps, SfuAppInput } from './plan/index.js';
-export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuPortsMappings, } from './plan/index.js';
+export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuCompose, } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, LoginHostBinding, LoginHostBindingsPort, LoginHostDiscoveryPort, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { NO_DOMAIN_ZONE, ownHostnames } from './plan/index.js';

package/dist/index.js

@@ -20,7 +20,7 @@ export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesF
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICES_APPLIED_SCOPE_KEY, OwnServicesBlockedError, orgTarget, } from './plan/index.js';
 export { OWN_AUTH_APPLIED_GIT_REF_SCOPE_KEY, OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY, OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, provisionFilesHost, provisionJobsHost, provisionMailServer, } from './plan/index.js';
-export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuPortsMappings, } from './plan/index.js';
+export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu, provisionSfuApp, sfuConfig, sfuCompose, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls, loginHostnameFor } from './plan/index.js';
 export { NO_DOMAIN_ZONE, ownHostnames } from './plan/index.js';
 export { ZITADEL_ORG_DOMAIN_SCOPE_KEY, ensureSignInOrg, registerSignInDomain, signInOrgDomain, } from './plan/index.js';

package/dist/plan/coolify-service.d.ts

@@ -0,0 +1,66 @@
+import type { DeployHealthRuntime } from './deploy-health.js';
+import type { CoolifyPort } from './executor.js';
+/**
+ * A Coolify "service": a Docker Compose file Coolify runs as one unit. Foundry
+ * uses it where an application cannot do the job. Coolify 4.4.2 takes
+ * `ports_mappings` on an application only as `^(\d+:\d+)(,\d+:\d+)*$`
+ * (`bootstrap/helpers/api.php:233`): no range and no `/udp`, so a media
+ * server's UDP range cannot be published that way. A service keeps the
+ * compose `ports` list as written (`bootstrap/helpers/parsers.php`,
+ * `serviceParser`: `$payload['ports'] = $ports`).
+ *
+ * Every call goes through `CoolifyPort.raw` with a time limit, and an error
+ * never carries a request body.
+ */
+type Raw = Pick<CoolifyPort, 'raw'>;
+/** The uuid of the service named `name` in the environment, or null. `GET /services` lists a team's services with their `environment_id` (`ServicesController::services`). */
+export declare function findComposeService(coolify: Raw, name: string, environmentId: number): Promise<string | null>;
+export interface CreateComposeServiceInput {
+    project_uuid: string;
+    server_uuid: string;
+    environment_name: string;
+    environment_uuid: string;
+    /** Required by Coolify when the server has more than one destination (`ServicesController::create_service`). */
+    destination_uuid?: string;
+    name: string;
+    description: string;
+    /** The compose file as text; sent base64 encoded. */
+    compose: string;
+}
+/**
+ * `POST /services` with `docker_compose_raw`, then `PATCH` with
+ * `connect_to_docker_network`, which makes the container join the
+ * destination's network under the alias `<service key>-<service uuid>`
+ * (`StartService.php`), which the tunnel dials. The create cannot carry the
+ * flag: Coolify 4.4.2 checks its fields against the list for every create
+ * first, which lacks it (`ServicesController.php:391`), and answers 422.
+ * A PATCH that fails leaves the service without the flag; the next run finds
+ * it and `updateComposeService` sets it. Nothing starts: `instant_deploy` is false.
+ */
+export declare function createComposeService(coolify: Raw, input: CreateComposeServiceInput): Promise<string>;
+/** `PATCH /services/{uuid}`: the compose file and the network flag. Coolify parses the file again; nothing restarts. */
+export declare function updateComposeService(coolify: Raw, uuid: string, compose: string): Promise<void>;
+/** `GET /services/{uuid}`: its `status` is `running:healthy`, `exited:unhealthy`, ... (the model appends it). */
+export declare function composeServiceStatus(coolify: Raw, uuid: string): Promise<string>;
+/** Coolify refuses `start` of a service whose status contains "running" (`action_deploy`), so the same test decides. */
+export declare const composeServiceRuns: (status: string) => boolean;
+/** One env value of the service's production rows, or undefined. */
+export declare function composeServiceEnv(coolify: Raw, uuid: string, key: string): Promise<string | undefined>;
+/**
+ * `PATCH /services/{uuid}/envs/bulk`. `is_literal` and `is_multiline` both
+ * single-quote the value in the service's `.env` (`EnvironmentVariable.php`
+ * `real_value`), so `$` is never interpolated and a newline stays in it.
+ */
+export declare function upsertComposeServiceEnv(coolify: Raw, uuid: string, env: {
+    key: string;
+    value: string;
+}): Promise<void>;
+/**
+ * Runs the service's current compose file and env. A service has no
+ * deployment record to wait on, so a running service is stopped first and
+ * the wait for "not running" comes before `start`: the old status can never
+ * be read as the new one (rule 5). Then `start` and the wait for "running".
+ * A service that is not running is only started.
+ */
+export declare function redeployComposeService(coolify: Raw, uuid: string, runtime: DeployHealthRuntime, label: string): Promise<void>;
+export {};

package/dist/plan/coolify-service.js

@@ -0,0 +1,126 @@
+import { OWN_LIMITS_TIMEOUT_MS } from './own-limits.js';
+const SERVICE_WAIT_MS = 300_000;
+const SERVICE_POLL_INTERVAL_MS = 5_000;
+async function call(coolify, what, method, path, body) {
+    let timer;
+    try {
+        return await Promise.race([
+            coolify.raw(method, path, body),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${what}: Coolify did not answer within ${OWN_LIMITS_TIMEOUT_MS / 1000}s`)), OWN_LIMITS_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The uuid of the service named `name` in the environment, or null. `GET /services` lists a team's services with their `environment_id` (`ServicesController::services`). */
+export async function findComposeService(coolify, name, environmentId) {
+    const rows = await call(coolify, 'listing services', 'GET', '/services');
+    if (!Array.isArray(rows))
+        throw new Error('listing services: Coolify answered with no list');
+    for (const row of rows) {
+        if (isRecord(row) &&
+            row.name === name &&
+            row.environment_id === environmentId &&
+            typeof row.uuid === 'string') {
+            return row.uuid;
+        }
+    }
+    return null;
+}
+/**
+ * `POST /services` with `docker_compose_raw`, then `PATCH` with
+ * `connect_to_docker_network`, which makes the container join the
+ * destination's network under the alias `<service key>-<service uuid>`
+ * (`StartService.php`), which the tunnel dials. The create cannot carry the
+ * flag: Coolify 4.4.2 checks its fields against the list for every create
+ * first, which lacks it (`ServicesController.php:391`), and answers 422.
+ * A PATCH that fails leaves the service without the flag; the next run finds
+ * it and `updateComposeService` sets it. Nothing starts: `instant_deploy` is false.
+ */
+export async function createComposeService(coolify, input) {
+    const { compose, ...rest } = input;
+    const created = await call(coolify, `creating service ${input.name}`, 'POST', '/services', {
+        ...rest,
+        docker_compose_raw: Buffer.from(compose, 'utf8').toString('base64'),
+        instant_deploy: false,
+    });
+    const uuid = isRecord(created) ? created.uuid : undefined;
+    if (typeof uuid !== 'string' || uuid === '') {
+        throw new Error(`creating service ${input.name}: Coolify answered with no uuid`);
+    }
+    await call(coolify, `updating service ${uuid}`, 'PATCH', `/services/${uuid}`, {
+        connect_to_docker_network: true,
+    });
+    return uuid;
+}
+/** `PATCH /services/{uuid}`: the compose file and the network flag. Coolify parses the file again; nothing restarts. */
+export async function updateComposeService(coolify, uuid, compose) {
+    await call(coolify, `updating service ${uuid}`, 'PATCH', `/services/${uuid}`, {
+        docker_compose_raw: Buffer.from(compose, 'utf8').toString('base64'),
+        connect_to_docker_network: true,
+    });
+}
+/** `GET /services/{uuid}`: its `status` is `running:healthy`, `exited:unhealthy`, ... (the model appends it). */
+export async function composeServiceStatus(coolify, uuid) {
+    const row = await call(coolify, `reading service ${uuid}`, 'GET', `/services/${uuid}`);
+    const status = isRecord(row) ? row.status : undefined;
+    return typeof status === 'string' ? status : '';
+}
+/** Coolify refuses `start` of a service whose status contains "running" (`action_deploy`), so the same test decides. */
+export const composeServiceRuns = (status) => status.includes('running');
+/** One env value of the service's production rows, or undefined. */
+export async function composeServiceEnv(coolify, uuid, key) {
+    const rows = await call(coolify, `reading the envs of service ${uuid}`, 'GET', `/services/${uuid}/envs`);
+    if (!Array.isArray(rows))
+        throw new Error(`reading the envs of service ${uuid}: no list`);
+    for (const row of rows) {
+        if (isRecord(row) && row.key === key && row.is_preview !== true) {
+            return typeof row.value === 'string' ? row.value : undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * `PATCH /services/{uuid}/envs/bulk`. `is_literal` and `is_multiline` both
+ * single-quote the value in the service's `.env` (`EnvironmentVariable.php`
+ * `real_value`), so `$` is never interpolated and a newline stays in it.
+ */
+export async function upsertComposeServiceEnv(coolify, uuid, env) {
+    await call(coolify, `writing the envs of service ${uuid}`, 'PATCH', `/services/${uuid}/envs/bulk`, {
+        data: [{ key: env.key, value: env.value, is_literal: true, is_multiline: true }],
+    });
+}
+async function waitFor(coolify, uuid, want, runtime, label, what) {
+    const sleep = runtime.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? SERVICE_WAIT_MS;
+    const interval = runtime.readyIntervalMs ?? SERVICE_POLL_INTERVAL_MS;
+    const deadline = now() + timeout;
+    for (;;) {
+        if (want(await composeServiceStatus(coolify, uuid)))
+            return;
+        if (now() >= deadline) {
+            throw new Error(`${label}: service ${uuid} did not ${what} within ${Math.round(timeout / 1000)}s. Apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * Runs the service's current compose file and env. A service has no
+ * deployment record to wait on, so a running service is stopped first and
+ * the wait for "not running" comes before `start`: the old status can never
+ * be read as the new one (rule 5). Then `start` and the wait for "running".
+ * A service that is not running is only started.
+ */
+export async function redeployComposeService(coolify, uuid, runtime, label) {
+    if (composeServiceRuns(await composeServiceStatus(coolify, uuid))) {
+        await call(coolify, `stopping service ${uuid}`, 'POST', `/services/${uuid}/stop`);
+        await waitFor(coolify, uuid, (s) => !composeServiceRuns(s), runtime, label, 'stop');
+    }
+    await call(coolify, `starting service ${uuid}`, 'POST', `/services/${uuid}/start`);
+    await waitFor(coolify, uuid, (s) => composeServiceRuns(s) && !s.includes('unhealthy'), runtime, label, 'run');
+}

package/dist/plan/executor.js

@@ -5903,7 +5903,11 @@ export class FoundryStepExecutor {
             throw new Error(OWN_SERVICES_PORT_ABSENT);
         const scope = scopeFromOrg(context, {});
         const { sfu } = own.provision;
+        const sfuRaw = sfu.coolify;
+        const listing = typeof sfuRaw.raw === 'function' ? sfuRaw : this.rawCoolify;
         return provisionSfuApp(scope, {
+            // The connector app goes through `placedForCompany` and `limited`; the media server is a service and names its destination itself.
+            destinationFor: (serverUuid) => this.companyDestination(listing, org, context, serverUuid),
             coolify: limited(this.placedForCompany(sfu.coolify, org, context), LIMITS.ownSfu),
             network: orgNetwork({ dns: this.dnsPort(), tunnels: this.tunnelPort(), zones: this.zonePort() }, scope, `${org.slug}:sfu`),
             deliverSecret: sfu.deliverSecret,

package/dist/plan/index.d.ts

@@ -13,7 +13,7 @@ export { OWN_AUTH_APPLIED_GIT_REF_SCOPE_KEY, OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY
 export type { PlanOwnSfuOptions } from './own-diff.js';
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu } from './own-diff.js';
 export type { SfuAppDeps, SfuAppInput } from './own-sfu.js';
-export { provisionSfuApp, sfuConfig, sfuPortsMappings } from './own-sfu.js';
+export { provisionSfuApp, sfuCompose, sfuConfig } from './own-sfu.js';
 export type { OwnAuthInstance, FilesKeysMint, FilesKeysMinted, OwnFilesDeps, OwnFilesR2Key, OwnFilesR2Keys, OwnServicePorts, OwnServicesPort, OwnServicesProvision, OwnSfuDeps, ProjectSource, ServiceNetwork, ServiceTarget, StepScope, } from './own-services.js';
 export { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICES_APPLIED_SCOPE_KEY, OwnServicesBlockedError, orgNetwork, orgTarget, platformNetwork, platformTarget, scopeFromOrg, scopeFromPlatform, } from './own-services.js';
 export type { PlatformOrgClientFactories } from './platform-org-ports.js';

package/dist/plan/index.js

@@ -5,7 +5,7 @@ export { planPlatform, toPlatformPlan, JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDUL
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesForOwn, agoraHostValuesFromPlatform, heldOwnKeyRefs, heldPlatformKeyRefs, orgPlatformReadinessFor, orgPlatformReadinessFrom, } from './platform-org.js';
 export { OWN_AUTH_APPLIED_GIT_REF_SCOPE_KEY, OWN_AUTH_APPLIED_HOSTNAME_SCOPE_KEY, OWN_AUTH_BLOCKED_KEY, OWN_FILES_BLOCKED_KEY, OWN_FILES_R2_BLOCKED_KEY, OWN_JOBS_BLOCKED_KEY, OWN_MAIL_BLOCKED_KEY, planOwnAuth, planOwnFiles, planOwnFilesR2, planOwnJobs, planOwnMail, } from './own-diff.js';
 export { OWN_SFU_BLOCKED_KEY, OWN_SFU_FIREWALL_KEY, planOwnSfu } from './own-diff.js';
-export { provisionSfuApp, sfuConfig, sfuPortsMappings } from './own-sfu.js';
+export { provisionSfuApp, sfuCompose, sfuConfig } from './own-sfu.js';
 export { OWN_FILES_R2_SCOPE_KEY, OWN_FILES_R2_UNDELIVERED_SCOPE_KEY, OWN_SERVICES_APPLIED_SCOPE_KEY, OwnServicesBlockedError, orgNetwork, orgTarget, platformNetwork, platformTarget, scopeFromOrg, scopeFromPlatform, } from './own-services.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
 export { AdoptRefusedError } from './adopt.js';

package/dist/plan/own-diff.js

@@ -338,7 +338,7 @@ export function planOwnSfu(options) {
     });
     const undelivered = recordedIds[OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY];
     if (undelivered && !options.keysHeld) {
-        return result(null, `${org.slug}'s own media server LiveKit key for app ${undelivered} was minted but not confirmed delivered; remove the recorded key ${OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        return result(null, `${org.slug}'s own media server LiveKit key for service ${undelivered} was minted but not confirmed delivered; remove the recorded key ${OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY} to mint a new one`);
     }
     if (!ownServices) {
         return result(null, `${org.slug}'s own media server is blocked, not planned: the host supplies no ownServices port`);

package/dist/plan/own-sfu.d.ts

@@ -1,16 +1,21 @@
 import { type LivekitCredentials } from '../calls-sfu-keys.js';
 import { type CallsSfuUrls } from '../calls-sfu.js';
-import { type DeployHealthRuntime } from './deploy-health.js';
+import type { DeployHealthRuntime } from './deploy-health.js';
 import type { FoundryStepExecutorPorts } from './executor.js';
 import type { OwnSfuDeps, ProjectSource, ServiceNetwork, ServiceTarget, StepScope } from './own-services.js';
 /** The LiveKit image, the same repository the shared SFU runs. */
 export declare const OWN_SFU_IMAGE = "livekit/livekit-server";
-export declare const OWN_SFU_APP_SCOPE_KEY = "coolify_own_sfu_app";
+/**
+ * The Coolify service (not application) that runs the media server. The earlier
+ * `coolify_own_sfu_app` key named an application Coolify refused to create; it
+ * is no longer read or written, and a value left under it is ignored.
+ */
+export declare const OWN_SFU_SERVICE_SCOPE_KEY = "coolify_own_sfu_service";
 export declare const OWN_SFU_TUNNEL_SCOPE_KEY = "cloudflare_own_sfu_tunnel";
 export declare const OWN_SFU_CONNECTOR_APP_SCOPE_KEY = "coolify_own_sfu_connector_app";
-/** Set to the app id before the key pair leaves, cleared after the pair is delivered and written to the app. */
+/** Set to the service uuid before the key pair leaves, cleared after the pair is delivered and written to the service. */
 export declare const OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY = "own_sfu_keys_undelivered";
-/** The app id once the company's key pair is delivered and in the app's env. */
+/** The service uuid once the company's key pair is delivered and in the service's env. */
 export declare const OWN_SFU_KEYS_SCOPE_KEY = "own_sfu_keys_set";
 export declare const OWN_SFU_DEPLOY_PENDING_SCOPE_KEY = "own_sfu_deploy_pending";
 export declare const OWN_SFU_APPLIED_VERSION_SCOPE_KEY = "own_sfu_applied_version";
@@ -28,6 +33,8 @@ export interface SfuAppDeps {
     mintLivekitCredentials?: () => LivekitCredentials;
     /** Called with every secret value this step handles, so the caller can scrub it from output. */
     onSecret?: (value: string) => void;
+    /** The company's Docker destination on a server. Without it the create names none. */
+    destinationFor?: (serverUuid: string) => Promise<string | undefined>;
 }
 export interface SfuAppInput {
     slot: number;
@@ -39,10 +46,33 @@ export interface SfuAppInput {
     version: string;
     project: ProjectSource;
 }
-/** The Docker `ports_mappings` string for a slot: the UDP range and the TCP fallback port, one to one. */
-export declare function sfuPortsMappings(slot: number): string;
+/** The compose `ports` lines for a slot: the UDP range and the TCP fallback port, one to one. */
+export declare function sfuComposePorts(slot: number): string[];
+/** The image the service runs: the pinned tag carries the platform's digest, any other declared tag goes as declared. */
+export declare function sfuImageRef(version: string): string;
+/**
+ * The compose file of the media server. `serviceName` is the compose service
+ * key. Read from Coolify 4.4.2 (tag v4.4.2 source):
+ * - the container is named `<key>-<service uuid>` (`bootstrap/helpers/parsers.php:2711`);
+ * - with `connect_to_docker_network` set, `StartService` runs `docker network connect
+ *   --alias <that name> <destination network> <that name>`
+ *   (`app/Actions/Service/StartService.php:59-65`), so the tunnel on the destination
+ *   network reaches port 7880 at that name;
+ * - the compose `ports` list is kept as written (`parsers.php`, `$payload['ports'] = $ports`),
+ *   where an application refuses a port range and a protocol suffix in its mappings
+ *   (`bootstrap/helpers/api.php:233`).
+ * The config reaches the container only as `${LIVEKIT_CONFIG}`, a service env.
+ */
+export declare function sfuCompose(input: {
+    serviceName: string;
+    slot: number;
+    version: string;
+}): string;
 /**
- * LiveKit takes its whole config from one env value. `node_ip` is the
+ * LiveKit takes its whole config from one env value. It ends without a
+ * newline: Coolify trims every stored env value (EnvironmentVariable.php:462),
+ * so a trailing one would never match what is read back, and every apply
+ * would restart the media server. `node_ip` is the
  * server's address: the app is not on the host network, so the media ports
  * reach it through the published mappings.
  */
@@ -52,11 +82,13 @@ export declare function sfuConfig(input: {
     keys: LivekitCredentials;
 }): string;
 /**
- * One company's LiveKit media server as a Coolify app: the image, its slot's
- * ports published to the server, and a tunnel for signalling at `sfu.<domain>`.
- * The company's single key pair is minted once, delivered to
- * `target.refs.livekitKeys` as JSON, and written to the app's env; it is never
- * recorded. Rules 1 to 6 of `CLAUDE.md` "Platform steps".
+ * One company's LiveKit media server as a Coolify service (a compose file): the
+ * image, its slot's ports published to the server, and a tunnel for signalling
+ * at `sfu.<domain>`. It is a service because an application cannot publish a
+ * UDP range (`coolify-service.ts`). The company's single key pair is minted
+ * once, delivered to `target.refs.livekitKeys` as JSON, and written to the
+ * service's env; it is never recorded. Rules 1 to 6 of `CLAUDE.md` "Platform
+ * steps". An application of the same name is never read or changed.
  */
 export declare function provisionSfuApp(scope: StepScope, deps: SfuAppDeps, target: ServiceTarget, input: SfuAppInput): Promise<{
     resourceId?: string;

package/dist/plan/own-sfu.js

@@ -1,18 +1,22 @@
-import { coolifyImageFor } from '../bootstrap/versions.js';
+import { DIGESTS, VERSIONS } from '../bootstrap/versions.js';
 import { mintLivekitCredentials } from '../calls-sfu-keys.js';
 import { LIVEKIT_SIGNALLING_PORT, sfuSlotPorts } from '../calls-sfu.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
-import { waitForNewDeployment } from './deploy-health.js';
-import { healthCheckSettings } from './health-check-settings.js';
+import { composeServiceEnv, composeServiceRuns, composeServiceStatus, createComposeService, findComposeService, redeployComposeService, updateComposeService, upsertComposeServiceEnv, } from './coolify-service.js';
 import { recordOwnDnsHostname } from './own-dns.js';
 /** The LiveKit image, the same repository the shared SFU runs. */
 export const OWN_SFU_IMAGE = 'livekit/livekit-server';
-export const OWN_SFU_APP_SCOPE_KEY = 'coolify_own_sfu_app';
+/**
+ * The Coolify service (not application) that runs the media server. The earlier
+ * `coolify_own_sfu_app` key named an application Coolify refused to create; it
+ * is no longer read or written, and a value left under it is ignored.
+ */
+export const OWN_SFU_SERVICE_SCOPE_KEY = 'coolify_own_sfu_service';
 export const OWN_SFU_TUNNEL_SCOPE_KEY = 'cloudflare_own_sfu_tunnel';
 export const OWN_SFU_CONNECTOR_APP_SCOPE_KEY = 'coolify_own_sfu_connector_app';
-/** Set to the app id before the key pair leaves, cleared after the pair is delivered and written to the app. */
+/** Set to the service uuid before the key pair leaves, cleared after the pair is delivered and written to the service. */
 export const OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY = 'own_sfu_keys_undelivered';
-/** The app id once the company's key pair is delivered and in the app's env. */
+/** The service uuid once the company's key pair is delivered and in the service's env. */
 export const OWN_SFU_KEYS_SCOPE_KEY = 'own_sfu_keys_set';
 export const OWN_SFU_DEPLOY_PENDING_SCOPE_KEY = 'own_sfu_deploy_pending';
 export const OWN_SFU_APPLIED_VERSION_SCOPE_KEY = 'own_sfu_applied_version';
@@ -22,13 +26,50 @@ export const SFU_INTERNAL_URL_SCOPE_KEY = 'sfu_internal_url';
 export const SFU_PUBLIC_URL_SCOPE_KEY = 'sfu_public_url';
 const KEYS_DELIVERY_ATTEMPTS = 3;
 const CONFIG_ENV = 'LIVEKIT_CONFIG';
-/** The Docker `ports_mappings` string for a slot: the UDP range and the TCP fallback port, one to one. */
-export function sfuPortsMappings(slot) {
+/** The compose `ports` lines for a slot: the UDP range and the TCP fallback port, one to one. */
+export function sfuComposePorts(slot) {
     const { udpStart, udpEnd, tcp } = sfuSlotPorts(slot);
-    return `${udpStart}-${udpEnd}:${udpStart}-${udpEnd}/udp,${tcp}:${tcp}`;
+    return [`${udpStart}-${udpEnd}:${udpStart}-${udpEnd}/udp`, `${tcp}:${tcp}/tcp`];
+}
+/** The image the service runs: the pinned tag carries the platform's digest, any other declared tag goes as declared. */
+export function sfuImageRef(version) {
+    return version === VERSIONS.livekit
+        ? `${OWN_SFU_IMAGE}:${version}@${DIGESTS.livekit}`
+        : `${OWN_SFU_IMAGE}:${version}`;
 }
 /**
- * LiveKit takes its whole config from one env value. `node_ip` is the
+ * The compose file of the media server. `serviceName` is the compose service
+ * key. Read from Coolify 4.4.2 (tag v4.4.2 source):
+ * - the container is named `<key>-<service uuid>` (`bootstrap/helpers/parsers.php:2711`);
+ * - with `connect_to_docker_network` set, `StartService` runs `docker network connect
+ *   --alias <that name> <destination network> <that name>`
+ *   (`app/Actions/Service/StartService.php:59-65`), so the tunnel on the destination
+ *   network reaches port 7880 at that name;
+ * - the compose `ports` list is kept as written (`parsers.php`, `$payload['ports'] = $ports`),
+ *   where an application refuses a port range and a protocol suffix in its mappings
+ *   (`bootstrap/helpers/api.php:233`).
+ * The config reaches the container only as `${LIVEKIT_CONFIG}`, a service env.
+ */
+export function sfuCompose(input) {
+    return [
+        'services:',
+        `  ${input.serviceName}:`,
+        `    image: "${sfuImageRef(input.version)}"`,
+        '    restart: unless-stopped',
+        '    environment:',
+        `      - "${CONFIG_ENV}=\${${CONFIG_ENV}}"`,
+        '    ports:',
+        ...sfuComposePorts(input.slot).map((p) => `      - "${p}"`),
+        '    mem_limit: 1g',
+        '    cpus: 1',
+        '',
+    ].join('\n');
+}
+/**
+ * LiveKit takes its whole config from one env value. It ends without a
+ * newline: Coolify trims every stored env value (EnvironmentVariable.php:462),
+ * so a trailing one would never match what is read back, and every apply
+ * would restart the media server. `node_ip` is the
  * server's address: the app is not on the host network, so the media ports
  * reach it through the published mappings.
  */
@@ -44,7 +85,6 @@ export function sfuConfig(input) {
         `  node_ip: ${input.nodeIp}`,
         'keys:',
         `  ${input.keys.apiKey}: ${input.keys.apiSecret}`,
-        '',
     ].join('\n');
 }
 function heldPairOf(value) {
@@ -71,11 +111,13 @@ function keysOf(config) {
 }
 const KEY_PAIR_SHAPE = /^[A-Za-z0-9]{8,128}$/;
 /**
- * One company's LiveKit media server as a Coolify app: the image, its slot's
- * ports published to the server, and a tunnel for signalling at `sfu.<domain>`.
- * The company's single key pair is minted once, delivered to
- * `target.refs.livekitKeys` as JSON, and written to the app's env; it is never
- * recorded. Rules 1 to 6 of `CLAUDE.md` "Platform steps".
+ * One company's LiveKit media server as a Coolify service (a compose file): the
+ * image, its slot's ports published to the server, and a tunnel for signalling
+ * at `sfu.<domain>`. It is a service because an application cannot publish a
+ * UDP range (`coolify-service.ts`). The company's single key pair is minted
+ * once, delivered to `target.refs.livekitKeys` as JSON, and written to the
+ * service's env; it is never recorded. Rules 1 to 6 of `CLAUDE.md` "Platform
+ * steps". An application of the same name is never read or changed.
  */
 export async function provisionSfuApp(scope, deps, target, input) {
     const { coolify, network, deliverSecret, runtime } = deps;
@@ -92,47 +134,43 @@ export async function provisionSfuApp(scope, deps, target, input) {
         throw new Error(`${label}: no usable Coolify server is registered`);
     if (!server.ip)
         throw new Error(`${label}: the Coolify server has no address to give LiveKit`);
-    const existingApp = await coolify.findApplicationByName(target.names.sfuApp, {
-        environmentIds: [environment.id],
+    const compose = sfuCompose({
+        serviceName: target.internal.sfu,
+        slot: input.slot,
+        version: input.version,
     });
-    let appId;
-    if (existingApp) {
-        appId = existingApp.uuid;
+    const existingService = await findComposeService(coolify, target.names.sfuApp, environment.id);
+    let serviceId;
+    if (existingService) {
+        serviceId = existingService;
+        // Set on every run: a declared version or slot reaches an existing service here.
+        await updateComposeService(coolify, serviceId, compose);
     }
     else {
-        appId = (await coolify.createDockerImageApplication({
+        const destination = await deps.destinationFor?.(server.uuid);
+        serviceId = await createComposeService(coolify, {
             project_uuid: projectUuid,
             server_uuid: server.uuid,
             environment_name: environment.name,
             environment_uuid: environment.uuid,
-            ...coolifyImageFor('livekit', OWN_SFU_IMAGE, input.version),
-            ports_exposes: String(LIVEKIT_SIGNALLING_PORT),
-            ports_mappings: sfuPortsMappings(input.slot),
+            ...(destination ? { destination_uuid: destination } : {}),
             name: target.names.sfuApp,
             description: `LiveKit media server for ${target.id}`,
-            instant_deploy: false,
-        })).uuid;
+            compose,
+        });
     }
-    scope.recordScopeId(OWN_SFU_APP_SCOPE_KEY, appId);
+    scope.recordScopeId(OWN_SFU_SERVICE_SCOPE_KEY, serviceId);
     const recorded = scope.recordedIds();
     const changed = recorded[OWN_SFU_APPLIED_VERSION_SCOPE_KEY] !== input.version ||
         recorded[OWN_SFU_APPLIED_SLOT_SCOPE_KEY] !== String(input.slot) ||
         recorded[OWN_SFU_APPLIED_HOSTNAME_SCOPE_KEY] !== input.hostname;
-    // Set on every run: a declared version or slot reaches an existing app here.
-    await coolify.updateApplication(appId, {
-        custom_internal_name: target.internal.sfu,
-        ...coolifyImageFor('livekit', OWN_SFU_IMAGE, input.version),
-        ports_exposes: String(LIVEKIT_SIGNALLING_PORT),
-        ports_mappings: sfuPortsMappings(input.slot),
-        ...healthCheckSettings('/', LIVEKIT_SIGNALLING_PORT),
-    });
-    const liveConfig = (await coolify.listEnvs(appId)).find((e) => e.key === CONFIG_ENV && !e.is_preview)?.value;
+    const liveConfig = await composeServiceEnv(coolify, serviceId, CONFIG_ENV);
     let keys;
     let keysJustSet = false;
     if (scope.recordedIds()[OWN_SFU_KEYS_SCOPE_KEY]) {
         const held = keysOf(liveConfig);
         if (!held) {
-            throw new Error(`${label}: the app's ${CONFIG_ENV} no longer holds the company's key`);
+            throw new Error(`${label}: the service's ${CONFIG_ENV} no longer holds the company's key`);
         }
         keys = held;
         deps.onSecret?.(keys.apiSecret);
@@ -156,7 +194,7 @@ export async function provisionSfuApp(scope, deps, target, input) {
                 throw new Error(`${label}: the minted LiveKit key has characters the config cannot hold`);
             }
             deps.onSecret?.(keys.apiSecret);
-            scope.recordScopeId(OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY, appId);
+            scope.recordScopeId(OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY, serviceId);
             await scope.persist();
             let delivered = false;
             const payload = JSON.stringify({ apiKey: keys.apiKey, apiSecret: keys.apiSecret });
@@ -184,21 +222,23 @@ export async function provisionSfuApp(scope, deps, target, input) {
         await scope.persist();
     }
     if (envChanged) {
-        await coolify.bulkUpsertEnvs(appId, [{ key: CONFIG_ENV, value: config, literal: true }]);
+        await upsertComposeServiceEnv(coolify, serviceId, { key: CONFIG_ENV, value: config });
     }
     if (keysJustSet) {
-        scope.recordScopeId(OWN_SFU_KEYS_SCOPE_KEY, appId);
+        scope.recordScopeId(OWN_SFU_KEYS_SCOPE_KEY, serviceId);
         scope.recordScopeId(OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY, '');
         await scope.persist();
     }
-    const running = (await coolify.getApplication(appId)).status?.startsWith('running') ?? false;
-    if (!existingApp || pending || !running) {
-        await waitForNewDeployment(coolify, appId, { kind: 'deployment-only' }, runtime, runtime.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))), label, 'the media server keeps its old version');
+    const running = composeServiceRuns(await composeServiceStatus(coolify, serviceId));
+    if (!existingService || pending || !running) {
+        await redeployComposeService(coolify, serviceId, runtime, label);
     }
     if (pending) {
         scope.recordScopeId(OWN_SFU_DEPLOY_PENDING_SCOPE_KEY, '');
         await scope.persist();
     }
+    // The container's alias on the destination network: `<service key>-<service uuid>`.
+    const signalling = `http://${target.internal.sfu}-${serviceId}:${LIVEKIT_SIGNALLING_PORT}`;
     const tunnels = await network.tunnels();
     const tunnel = (await tunnels.findTunnelByName(target.names.sfuTunnel)) ??
         (await tunnels.createTunnel(target.names.sfuTunnel));
@@ -207,7 +247,7 @@ export async function provisionSfuApp(scope, deps, target, input) {
         ingress: [
             {
                 hostname: input.hostname,
-                service: `http://${target.internal.sfu}:${LIVEKIT_SIGNALLING_PORT}`,
+                service: signalling,
             },
             { service: 'http_status:404' },
         ],
@@ -238,9 +278,9 @@ export async function provisionSfuApp(scope, deps, target, input) {
     scope.recordScopeId(OWN_SFU_APPLIED_VERSION_SCOPE_KEY, input.version);
     scope.recordScopeId(OWN_SFU_APPLIED_SLOT_SCOPE_KEY, String(input.slot));
     scope.recordScopeId(OWN_SFU_APPLIED_HOSTNAME_SCOPE_KEY, input.hostname);
-    scope.recordScopeId(SFU_INTERNAL_URL_SCOPE_KEY, `http://${target.internal.sfu}:${LIVEKIT_SIGNALLING_PORT}`);
+    scope.recordScopeId(SFU_INTERNAL_URL_SCOPE_KEY, signalling);
     scope.recordScopeId(SFU_PUBLIC_URL_SCOPE_KEY, `https://${input.hostname}`);
-    return { resourceId: appId };
+    return { resourceId: serviceId };
 }
 /**
  * The addresses of the company's media server, from its recorded ids. Before

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.39.4",
+  "version": "0.39.6",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",