@podosoft/podokit 1.0.1 → 1.1.2

package/README.md

@@ -1,8 +1,8 @@
 # @podosoft/podokit
 
 PodoKit is an opinionated Bun 1.4.0 full-stack starter and CLI. It generates an
-Elysia API, a SvelteKit web application, PostgreSQL integration through native
-`Bun.SQL`, Tailwind CSS v4, shadcn-svelte, Docker, and k3s assets.
+Elysia API, a SvelteKit web application, selectable PostgreSQL/SQLite integration
+through native `Bun.SQL`, Tailwind CSS v4, shadcn-svelte, Docker, and k3s assets.
 
 The CLI itself remains Node-compatible, so either `npx` or `bunx` can create and
 maintain projects. Generated PodoKit v1 applications are Bun-only.
@@ -24,7 +24,7 @@ gateway on loopback port 80; later projects reuse it and route by hostname. Stop
 the project with `podo dev down`.
 
 The `todo` template generates a working SvelteKit UI, Elysia CRUD API, and
-PostgreSQL persistence:
+PostgreSQL or SQLite persistence:
 
 ![Generated todo app](https://raw.githubusercontent.com/podosoft-dev/podokit/main/docs/images/todo-app.png)
 
@@ -35,6 +35,8 @@ PostgreSQL persistence:
 | `podo create <name>` | Create a Bun project from `fullstack`, `todo`, or `base`. |
 | `podo add <module>` | Add a composable feature module. |
 | `podo remove <module>` | Remove a module conservatively. |
+| `podo provider list` | Show active database, cache, object storage, event, and job providers. |
+| `podo provider set <capability> <provider> [--apply]` | Preview or apply one provider change. |
 | `podo status` | Show the PodoKit version, modules, ownership tiers, and local edits. |
 | `podo diff` | List edited or deleted managed files. |
 | `podo doctor` | Check Bun and framework versions. |
@@ -42,7 +44,7 @@ PostgreSQL persistence:
 | `podo update [--apply]` | Preview or apply managed template and module updates. |
 | `podo eject <path...>` | Transfer managed files to application ownership. |
 | `podo dev <action>` | Manage the generated development containers. |
-| `podo deploy <action>` | Plan, apply, verify, or roll back an immutable Helm release. |
+| `podo deploy <action>` | Plan, apply, verify, or roll back an immutable Kubernetes or Docker Compose release. |
 
 ```text
 podo create <name> [options]
@@ -50,6 +52,7 @@ podo create <name> [options]
 Options:
   --template <name>  fullstack (default), todo, or base
   --dir <path>       Target directory (default: ./<name>)
+  --database <name>  postgres (default) or sqlite
   --no-ai            Omit generated AI-agent guidance
   -y, --yes          Accept defaults without prompts
   -h, --help         Show help
@@ -80,6 +83,17 @@ remain untouched.
 See the [module guide](https://github.com/podosoft-dev/podokit/blob/main/docs/modules.md)
 and [updating guide](https://github.com/podosoft-dev/podokit/blob/main/docs/updating.md).
 
+## Runtime providers
+
+Generated projects use stable capability contracts with server defaults
+(`postgres`, `redis`, `s3`, Redis events, and `bullmq`) and local alternatives
+(`sqlite`, memory cache/events, local files/jobs). `podo provider set` is a dry
+run by default and installs the selected implementation module on `--apply`.
+It changes code and configuration only; it never migrates or deletes data.
+
+See the [runtime provider guide](https://github.com/podosoft-dev/podokit/blob/main/docs/providers.md)
+before switching an existing project.
+
 ## Compatibility boundary
 
 PodoKit v1 does not convert projects generated by PodoKit 0.x. Existing projects
@@ -99,7 +113,7 @@ my-app/
 │   ├── api/        # Bun + Elysia + native Bun.SQL
 │   └── web/        # SvelteKit + Tailwind CSS v4 + shadcn-svelte
 ├── infra/
-│   ├── docker/     # PostgreSQL, Redis, and optional services
+│   ├── docker/     # provider-aware external services
 │   └── k3s/        # deployments, services, ingress, and examples
 ├── tests/          # Playwright API and browser tests
 ├── .podokit/       # assembly and managed-file metadata

package/dist/add.d.ts

@@ -1,4 +1,5 @@
 import { type TemplateVars } from "@podosoft/podokit-template-engine";
+import { type ProviderCapability } from "@podosoft/podokit-runtime";
 interface Injection {
     file: string;
     marker: string;
@@ -8,7 +9,13 @@ interface Injection {
 }
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
-export declare const SUPPORTED_MANIFEST_VERSION = 2;
+export declare const SUPPORTED_MANIFEST_VERSION = 3;
+export interface ModuleRuntimeConstraints {
+    /** Maximum safe API replicas for process-local providers. */
+    maxApiReplicas?: number;
+    /** Whether jobs must execute inside the API process. */
+    embeddedWorker?: boolean;
+}
 export interface ModulePathMove {
     /** Project-relative file or directory path from an older module layout. */
     from: string;
@@ -39,6 +46,12 @@ export interface ModuleManifest {
     name: string;
     description: string;
     requires?: string[];
+    /** Runtime capabilities that must have an implementation module installed. */
+    requiresCapabilities?: ProviderCapability[];
+    /** Provider implementations supplied by this module. */
+    provides?: Partial<Record<ProviderCapability, string>>;
+    /** Deployment restrictions introduced by this implementation. */
+    runtimeConstraints?: ModuleRuntimeConstraints;
     targetApp: string;
     dependencies?: Record<string, string>;
     devDependencies?: Record<string, string>;

package/dist/add.js

@@ -11,11 +11,11 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_module_1 = require("node:module");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
+const podokit_runtime_1 = require("@podosoft/podokit-runtime");
 const lockfile_1 = require("./lockfile");
-const toolchain_1 = require("./toolchain");
 /** Highest `module.manifest.json` schema version this CLI understands. A package
  *  module declaring a higher version is rejected rather than mis-applied. */
-exports.SUPPORTED_MANIFEST_VERSION = 2;
+exports.SUPPORTED_MANIFEST_VERSION = 3;
 /** Return the legacy targetApp package fields plus any additional app overlays. */
 function modulePackageOverlays(manifest) {
     const overlays = new Map();
@@ -88,6 +88,43 @@ function assertManifestVersion(name, manifest) {
     if ((manifest.manifestVersion ?? exports.SUPPORTED_MANIFEST_VERSION) > exports.SUPPORTED_MANIFEST_VERSION) {
         throw new Error(`Module "${name}" needs a newer PodoKit (manifest v${manifest.manifestVersion}, this CLI supports v${exports.SUPPORTED_MANIFEST_VERSION}). Update @podosoft/podokit.`);
     }
+    for (const capability of manifest.requiresCapabilities ?? []) {
+        if (!(0, podokit_runtime_1.isProviderCapability)(capability)) {
+            throw new Error(`Module "${name}" requires unknown capability "${capability}".`);
+        }
+    }
+    for (const [capability, provider] of Object.entries(manifest.provides ?? {})) {
+        if (!(0, podokit_runtime_1.isProviderCapability)(capability)
+            || typeof provider !== "string"
+            || !(0, podokit_runtime_1.isProviderName)(capability, provider)) {
+            throw new Error(`Module "${name}" declares invalid provider ${capability}=${String(provider)}.`);
+        }
+    }
+    const maxApiReplicas = manifest.runtimeConstraints?.maxApiReplicas;
+    if (maxApiReplicas !== undefined
+        && (!Number.isSafeInteger(maxApiReplicas) || maxApiReplicas < 1)) {
+        throw new Error(`Module "${name}" declares an invalid maxApiReplicas constraint.`);
+    }
+}
+function providerModuleName(projectRoot, modulesDir, capability) {
+    const project = (0, lockfile_1.readManifest)(projectRoot);
+    if (!project)
+        throw new Error("Provider capabilities require a PodoKit project manifest.");
+    const selected = project.providers[capability];
+    for (const available of listModules(modulesDir, projectRoot)) {
+        const resolved = resolveModule(available.name, modulesDir, projectRoot);
+        if (!resolved)
+            continue;
+        const provides = readModuleManifest(resolved.dir).provides;
+        if (provides?.[capability] === selected)
+            return available.name;
+    }
+    throw new Error(`No module provides the selected ${capability} provider "${selected}". ` +
+        `Choose another provider with podo provider set ${capability} <provider> --apply.`);
+}
+function requiredModules(projectRoot, modulesDir, manifest) {
+    const capabilities = (manifest.requiresCapabilities ?? []).map((capability) => providerModuleName(projectRoot, modulesDir, capability));
+    return [...new Set([...(manifest.requires ?? []), ...capabilities])];
 }
 function assertRequiredProjectFiles(projectRoot, name, manifest) {
     const contents = manifest.requiredProjectContents ?? {};
@@ -136,7 +173,7 @@ function assertModuleGraphPrerequisites(projectRoot, module, modulesDir, visited
     const manifest = readModuleManifest(resolved.dir);
     assertManifestVersion(module, manifest);
     assertRequiredProjectFiles(projectRoot, module, manifest);
-    for (const required of manifest.requires ?? []) {
+    for (const required of requiredModules(projectRoot, modulesDir, manifest)) {
         assertModuleGraphPrerequisites(projectRoot, required, modulesDir, visited, module);
     }
 }
@@ -267,7 +304,7 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     const projectManifest = (0, lockfile_1.readManifest)(projectRoot);
     const vars = {
         projectName: appName,
-        ...(projectManifest ? (0, toolchain_1.toolchainTemplateVars)(projectManifest.toolchain) : {}),
+        ...(projectManifest ? (0, lockfile_1.manifestTemplateVars)(projectManifest) : {}),
     };
     const manifest = readModuleManifest(moduleDir, vars);
     applied.add(module);
@@ -278,7 +315,7 @@ function applyModule(projectRoot, module, modulesDir, applied, adopt) {
     const preserved = [];
     const adopted = [];
     const touched = [];
-    for (const required of manifest.requires ?? []) {
+    for (const required of requiredModules(projectRoot, modulesDir, manifest)) {
         if (applied.has(required) || isApplied(projectRoot, modulesDir, required))
             continue;
         const result = applyModule(projectRoot, required, modulesDir, applied, adopt);

package/dist/create.d.ts

@@ -1,3 +1,4 @@
+import { type DatabaseProviderName, type ProviderSelections } from "@podosoft/podokit-runtime";
 import { DEFAULT_TEMPLATE } from "./templates";
 import { type Runtime, type Toolchain } from "./toolchain";
 export type PackageManager = "bun";
@@ -19,12 +20,15 @@ export interface CreateOptions {
     podokitVersion?: string;
     /** Include AI agent guidance (AGENTS.md, CLAUDE.md, editor rules). Defaults to true. */
     ai?: boolean;
+    /** Database implementation selected for the generated project. */
+    database?: DatabaseProviderName;
 }
 export interface CreateResult {
     projectDir: string;
     packageManager: Toolchain["packageManager"];
     toolchain: Toolchain;
     template: string;
+    providers: ProviderSelections;
 }
 /** Validate a project name: no path separators, npm-friendly characters. */
 export declare function assertValidName(name: string): void;

package/dist/create.js

@@ -6,6 +6,7 @@ exports.create = create;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
+const podokit_runtime_1 = require("@podosoft/podokit-runtime");
 const templates_1 = require("./templates");
 Object.defineProperty(exports, "DEFAULT_TEMPLATE", { enumerable: true, get: function () { return templates_1.DEFAULT_TEMPLATE; } });
 const lockfile_1 = require("./lockfile");
@@ -39,6 +40,11 @@ function create(options) {
     assertValidName(name);
     const template = options.template ?? templates_1.DEFAULT_TEMPLATE;
     const toolchain = (0, toolchain_1.resolveToolchain)(options.runtime, options.packageManager);
+    const database = options.database ?? "postgres";
+    if (!(0, podokit_runtime_1.isProviderName)("database", database)) {
+        throw new Error('Database provider must be either "postgres" or "sqlite".');
+    }
+    const providers = (0, podokit_runtime_1.resolveProviderSelections)({ database });
     const projectDir = options.targetDir
         ? (0, node_path_1.isAbsolute)(options.targetDir)
             ? options.targetDir
@@ -53,6 +59,7 @@ function create(options) {
     }
     const vars = {
         projectName: name,
+        ...(0, lockfile_1.providerTemplateVars)(providers),
         ...(0, toolchain_1.toolchainTemplateVars)(toolchain),
     };
     (0, podokit_template_engine_1.writeTree)((0, assemble_1.renderProjectTemplate)(templatesDir, template, vars), projectDir);
@@ -65,11 +72,13 @@ function create(options) {
         toolchain,
         answers: vars,
         version: options.podokitVersion,
+        providers,
     });
     return {
         projectDir,
         packageManager: toolchain.packageManager,
         toolchain,
         template,
+        providers,
     };
 }

package/dist/deploy-compose-profile.d.ts

@@ -68,6 +68,9 @@ export interface DockerComposeProfileV1 {
         host: string;
         bindAddress: string;
         port: number;
+        webSocketPaths: string[];
+        trustedProxyCidrs: string[];
+        gatewayImage: string;
     };
     workloads: {
         api: ComposeWorkloadProfile;

package/dist/deploy-compose-profile.js

@@ -6,8 +6,10 @@ exports.initializeComposeProfile = initializeComposeProfile;
 exports.composeProfileDigest = composeProfileDigest;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
+const node_net_1 = require("node:net");
 const lockfile_1 = require("./lockfile");
 const deploy_schema_1 = require("./deploy-schema");
+const websocket_paths_1 = require("./websocket-paths");
 /** Decimal core count, e.g. "0.25" or "2". */
 const CPU_VALUE = /^(?:0\.[0-9]{1,3}|[1-9][0-9]{0,2}(?:\.[0-9]{1,3})?)$/;
 /** Compose byte suffix, e.g. "512m" or "2g". */
@@ -17,6 +19,31 @@ const PROJECT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
 /** An absolute POSIX path on the target host, with no traversal or control bytes. */
 const ABSOLUTE_PATH = /^\/(?:[A-Za-z0-9._-]+\/?)+$/;
 const VOLUME_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+function parseTrustedProxyCidrs(value, field) {
+    if (!Array.isArray(value)) {
+        throw new Error(`Deployment profile field "${field}" must be a string array.`);
+    }
+    const parsed = value.map((entry, index) => {
+        if (typeof entry !== "string" || entry !== entry.trim()) {
+            throw new Error(`Deployment profile field "${field}[${index}]" must be an IP CIDR block.`);
+        }
+        const separator = entry.lastIndexOf("/");
+        const address = entry.slice(0, separator);
+        const prefixText = entry.slice(separator + 1);
+        const family = (0, node_net_1.isIP)(address);
+        if (separator <= 0 ||
+            family === 0 ||
+            !/^(?:0|[1-9][0-9]*)$/.test(prefixText) ||
+            Number(prefixText) > (family === 4 ? 32 : 128)) {
+            throw new Error(`Deployment profile field "${field}[${index}]" must be an IP CIDR block.`);
+        }
+        return entry;
+    });
+    if (new Set(parsed).size !== parsed.length) {
+        throw new Error(`Deployment profile field "${field}" contains duplicate CIDR blocks.`);
+    }
+    return parsed.sort();
+}
 function validateCpu(value, field) {
     if (!CPU_VALUE.test(value)) {
         throw new Error(`Deployment profile field "${field}" must be a decimal CPU count.`);
@@ -134,7 +161,15 @@ function parseComposeProfile(value) {
     const migration = value.migration === undefined ? undefined : (0, deploy_schema_1.requiredRecord)(value, "migration");
     const sync = value.sync === undefined ? undefined : (0, deploy_schema_1.requiredRecord)(value, "sync");
     (0, deploy_schema_1.assertOnlyKeys)(target, ["context", "endpointFingerprint", "project"], "target");
-    (0, deploy_schema_1.assertOnlyKeys)(exposure, ["mode", "host", "bindAddress", "port"], "exposure");
+    (0, deploy_schema_1.assertOnlyKeys)(exposure, [
+        "mode",
+        "host",
+        "bindAddress",
+        "port",
+        "webSocketPaths",
+        "trustedProxyCidrs",
+        "gatewayImage",
+    ], "exposure");
     (0, deploy_schema_1.assertOnlyKeys)(workloads, ["api", "web", "worker"], "workloads");
     (0, deploy_schema_1.assertOnlyKeys)(dependencies, ["postgres", "redis", "objectStorage"], "dependencies");
     (0, deploy_schema_1.assertOnlyKeys)(secrets, ["api", "web", "registryLogin"], "secrets");
@@ -161,6 +196,15 @@ function parseComposeProfile(value) {
     const port = (0, deploy_schema_1.requiredNumber)(exposure, "port");
     if (port > 65535)
         throw new Error("Deployment exposure.port must be a TCP port.");
+    const webSocketPaths = (0, websocket_paths_1.parseExactWebSocketPaths)(exposure.webSocketPaths ?? [], "exposure.webSocketPaths");
+    const trustedProxyCidrs = parseTrustedProxyCidrs(exposure.trustedProxyCidrs ?? [], "exposure.trustedProxyCidrs");
+    if (trustedProxyCidrs.length > 0 && webSocketPaths.length === 0) {
+        throw new Error("Deployment exposure.trustedProxyCidrs requires at least one exposure.webSocketPaths entry.");
+    }
+    const gatewayImage = exposure.gatewayImage === undefined
+        ? "caddy:2.10-alpine"
+        : (0, deploy_schema_1.requiredString)(exposure, "gatewayImage");
+    (0, deploy_schema_1.validateImage)(gatewayImage, "exposure.gatewayImage");
     const web = parseComposeWorkload((0, deploy_schema_1.requiredRecord)(workloads, "web"), "workloads.web");
     // Compose has no load balancer. Two replicas of the service that publishes the
     // host port means the second one cannot bind it, and the deployment fails half
@@ -188,7 +232,15 @@ function parseComposeProfile(value) {
         driver: "docker-compose",
         target: { context, endpointFingerprint, project },
         release: (0, deploy_schema_1.parseReleaseProfile)((0, deploy_schema_1.requiredRecord)(value, "release")),
-        exposure: { mode: "publishedPort", host, bindAddress, port },
+        exposure: {
+            mode: "publishedPort",
+            host,
+            bindAddress,
+            port,
+            webSocketPaths,
+            trustedProxyCidrs,
+            gatewayImage,
+        },
         workloads: {
             api: parseComposeWorkload((0, deploy_schema_1.requiredRecord)(workloads, "api"), "workloads.api"),
             web,
@@ -249,6 +301,9 @@ function buildDefaultComposeProfile(projectName, options) {
             // network before TLS exists.
             bindAddress: "127.0.0.1",
             port: 8080,
+            webSocketPaths: [],
+            trustedProxyCidrs: [],
+            gatewayImage: "caddy:2.10-alpine",
         },
         workloads: {
             api: { replicas: 2, resources: { cpuLimit: "1", memoryLimit: "1g" } },
@@ -273,8 +328,8 @@ function buildDefaultComposeProfile(projectName, options) {
             },
             objectStorage: {
                 mode: "disabled",
-                image: "quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z",
-                clientImage: "quay.io/minio/mc:RELEASE.2025-08-13T08-35-41Z",
+                image: "pgsty/silo:RELEASE.2026-09-16T00-00-00Z",
+                clientImage: "pgsty/mc:RELEASE.2026-09-16T00-00-00Z",
                 envFile: `${secretsDirectory}/object-storage.env`,
                 requiredKeys: [
                     "MINIO_ROOT_PASSWORD",
@@ -319,12 +374,24 @@ function initializeComposeProfile(projectRoot, name, options) {
         throw new Error(`Deployment profile "${name}" already exists.`);
     const draft = buildDefaultComposeProfile(projectName, options);
     const modules = new Set(manifest.modules.map((module) => module.name));
-    const usesRedis = [...modules].some((module) => ["redis", "bullmq", "job-progress", "rate-limit", "sse"].includes(module));
+    const providers = manifest.providers;
+    const usesRedis = (providers.cache === "redis"
+        && ["redis", "rate-limit"].some((module) => modules.has(module)))
+        || (providers.events === "redis" && modules.has("sse"))
+        || (providers.jobs === "bullmq" && modules.has("bullmq"));
+    const usesEmbeddedProviders = providers.database === "sqlite"
+        || providers.cache === "memory"
+        || providers["object-storage"] === "local"
+        || providers.events === "memory"
+        || providers.jobs === "local";
+    draft.workloads.api.replicas = usesEmbeddedProviders ? 1 : 2;
+    draft.dependencies.postgres.mode = providers.database === "postgres" ? "managed" : "disabled";
     draft.dependencies.redis.mode = usesRedis ? "managed" : "disabled";
-    draft.dependencies.objectStorage.mode = modules.has("object-storage-s3")
+    draft.dependencies.objectStorage.mode = providers["object-storage"] === "s3"
+        && modules.has("object-storage-s3")
         ? "managed"
         : "disabled";
-    if (modules.has("bullmq")) {
+    if (providers.jobs === "bullmq" && modules.has("bullmq")) {
         draft.workloads.worker = { replicas: 1, resources: { cpuLimit: "0.5", memoryLimit: "512m" } };
     }
     const usesAuth = modules.has("auth");
@@ -336,7 +403,6 @@ function initializeComposeProfile(projectRoot, name, options) {
     draft.runtimeConfig = {
         ...draft.runtimeConfig,
         ...(usesAuth ? { BETTER_AUTH_URL: `https://${host}` } : {}),
-        ...(modules.has("sse") && usesRedis ? { SSE_TRANSPORT: "redis" } : {}),
         ...(modules.has("rate-limit")
             ? {
                 RATE_LIMIT_TTL: "60",

package/dist/deploy-compose-render.d.ts

@@ -18,6 +18,7 @@ export interface ComposeRuntime {
 export interface ComposeImages {
     api: string;
     web: string;
+    gateway: string | null;
     postgres: string | null;
     redis: string | null;
     objectStorage: string | null;
@@ -38,7 +39,7 @@ export declare function derivedRuntimeConfig(profile: DockerComposeProfileV1): R
  * the containers instead of leaving stale values running.
  */
 export declare function rolloutStateDigest(profile: DockerComposeProfileV1, secretIdentities: Record<string, string>): string;
-export declare function renderComposeDocument(profile: DockerComposeProfileV1, release: string, images: ComposeImages, stateDigest: string): string;
+export declare function renderComposeDocument(profile: DockerComposeProfileV1, release: string, images: ComposeImages, stateDigest: string, workerCommand?: string[]): string;
 /**
  * The migration runs as its own Compose project so it can be started, waited on,
  * and removed without touching the running application definition.

package/dist/deploy-compose-render.js

@@ -239,8 +239,46 @@ function applicationService(profile, role, image, release, stateDigest, options)
                 "    healthcheck:\n      disable: true\n") +
         labelsBlock(profile, release, stateDigest, "    "));
 }
-function renderComposeDocument(profile, release, images, stateDigest) {
+function gatewayService(profile, image, release, stateDigest) {
+    const globalOptions = profile.exposure.trustedProxyCidrs.length
+        ? `{
+  servers {
+    trusted_proxies static ${profile.exposure.trustedProxyCidrs.join(" ")}
+    trusted_proxies_strict
+  }
+}
+`
+        : "";
+    const caddyfile = globalOptions +
+        `:3000 {\n` +
+        `  @api_websockets path ${profile.exposure.webSocketPaths.join(" ")}\n` +
+        `  handle @api_websockets {\n` +
+        `    reverse_proxy ${serviceName(profile, "api")}:${CONTAINER_PORT}\n` +
+        `  }\n` +
+        `  handle {\n` +
+        `    reverse_proxy ${serviceName(profile, "web")}:${CONTAINER_PORT}\n` +
+        `  }\n` +
+        `}\n`;
+    const start = "printf '%s' \"$${CADDYFILE_CONTENT}\" > /tmp/Caddyfile\n" +
+        "exec caddy run --config /tmp/Caddyfile --adapter caddyfile";
+    return (`  ${serviceName(profile, "gateway")}:\n` +
+        `    image: ${quote(image)}\n` +
+        `    restart: unless-stopped\n` +
+        `    entrypoint: ["sh", "-c", ${quote(start)}]\n` +
+        environmentBlock({ CADDYFILE_CONTENT: caddyfile }, "    ") +
+        `    depends_on:\n` +
+        `      ${serviceName(profile, "api")}:\n        condition: service_healthy\n` +
+        `      ${serviceName(profile, "web")}:\n        condition: service_healthy\n` +
+        `    ports:\n      - ${quote(`${profile.exposure.bindAddress}:${profile.exposure.port}:${CONTAINER_PORT}`)}\n` +
+        `    networks: [${profile.target.project}]\n` +
+        `    healthcheck:\n` +
+        `      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:2019/config/"]\n` +
+        `      interval: 10s\n      timeout: 5s\n      retries: 6\n      start_period: 10s\n` +
+        labelsBlock(profile, release, stateDigest, "    "));
+}
+function renderComposeDocument(profile, release, images, stateDigest, workerCommand = ["bun", "dist/main-worker.js"]) {
     const services = [];
+    const hasGateway = profile.exposure.webSocketPaths.length > 0;
     if (profile.dependencies.postgres.mode === "managed" && images.postgres) {
         services.push(postgresService(profile, images.postgres));
     }
@@ -258,13 +296,19 @@ function renderComposeDocument(profile, release, images, stateDigest) {
     }));
     services.push(applicationService(profile, "web", images.web, release, stateDigest, {
         healthcheckPath: "/",
-        publish: true,
+        publish: !hasGateway,
     }));
+    if (hasGateway) {
+        if (!images.gateway) {
+            throw new Error("A resolved gateway image is required when WebSocket paths are configured.");
+        }
+        services.push(gatewayService(profile, images.gateway, release, stateDigest));
+    }
     if (profile.workloads.worker) {
         // The worker runs the API image with a different entry point, exactly as the
         // Kubernetes driver does.
         services.push(applicationService(profile, "worker", images.api, release, stateDigest, {
-            command: `["node", "dist/main-worker"]`,
+            command: `[${workerCommand.map((part) => quote(part)).join(", ")}]`,
         }));
     }
     const volumes = [
@@ -288,7 +332,7 @@ function renderComposeDocument(profile, release, images, stateDigest) {
  * The migration runs as its own Compose project so it can be started, waited on,
  * and removed without touching the running application definition.
  */
-function renderMigrationDocument(profile, release, images, defaultCommand = ["npm", "run", "migrate:all"]) {
+function renderMigrationDocument(profile, release, images, defaultCommand = ["bun", "run", "migrate:all"]) {
     const command = profile.migration?.command ?? defaultCommand;
     return (`# Generated by PodoKit. One-shot migration for ${release}.\n` +
         `name: ${profile.target.project}-migrate\n` +
@@ -306,6 +350,7 @@ function defaultComposeImages(profile, release) {
     return {
         api: `${profile.release.apiRepository}:${release}`,
         web: `${profile.release.webRepository}:${release}`,
+        gateway: profile.exposure.webSocketPaths.length > 0 ? profile.exposure.gatewayImage : null,
         postgres: profile.dependencies.postgres.mode === "managed"
             ? profile.dependencies.postgres.image
             : null,
@@ -325,8 +370,8 @@ function renderComposeDeployment(projectRoot, profileName, profile, release, res
     const root = (0, node_path_1.join)((0, node_path_1.resolve)(projectRoot), ".podokit", "runtime", "deploy", profileName);
     (0, node_fs_1.rmSync)(root, { recursive: true, force: true });
     (0, node_fs_1.mkdirSync)(root, { recursive: true });
-    const composeDocument = renderComposeDocument(profile, release, images, effectiveStateDigest);
     const toolchain = (0, lockfile_1.readManifest)(projectRoot)?.toolchain ?? (0, toolchain_1.resolveToolchain)();
+    const composeDocument = renderComposeDocument(profile, release, images, effectiveStateDigest, (0, toolchain_1.toolchainWorkerCommand)(toolchain));
     const migrationDocument = renderMigrationDocument(profile, release, images, (0, toolchain_1.toolchainMigrationCommand)(toolchain));
     const composeFile = (0, node_path_1.join)(root, "compose.yaml");
     const migrationFile = (0, node_path_1.join)(root, "compose.migrate.yaml");

package/dist/deploy-compose.js

@@ -150,6 +150,7 @@ function resolveComposeImages(profile, release, runner) {
     return {
         api: resolveImage(defaults.api, runner),
         web: resolveImage(defaults.web, runner),
+        gateway: defaults.gateway ? resolveImage(defaults.gateway, runner) : null,
         postgres: defaults.postgres ? resolveImage(defaults.postgres, runner) : null,
         redis: defaults.redis ? resolveImage(defaults.redis, runner) : null,
         objectStorage: defaults.objectStorage ? resolveImage(defaults.objectStorage, runner) : null,
@@ -372,7 +373,7 @@ function planComposeDeployment(projectRoot, profileName, release, runner = deplo
     actions.push({
         order: order++,
         kind: "application",
-        description: `Roll out api, web${profile.workloads.worker ? ", worker" : ""} and wait for health.`,
+        description: `Roll out api, web${profile.workloads.worker ? ", worker" : ""}${profile.exposure.webSocketPaths.length ? ", gateway" : ""} and wait for health.`,
     });
     actions.push({
         order: order++,

package/dist/deploy-profile.js

@@ -279,8 +279,19 @@ function initializeDeploymentProfile(projectRoot, name, options) {
         throw new Error("Project name cannot be converted to a Kubernetes release name.");
     const host = options.host ?? "app.example.com";
     const modules = new Set(manifest.modules.map((module) => module.name));
-    const usesRedis = [...modules].some((module) => ["redis", "bullmq", "job-progress", "rate-limit", "sse"].includes(module));
-    const usesObjectStorage = modules.has("object-storage-s3");
+    const providers = manifest.providers;
+    const usesPostgres = providers.database === "postgres";
+    const usesRedis = (providers.cache === "redis"
+        && ["redis", "rate-limit"].some((module) => modules.has(module)))
+        || (providers.events === "redis" && modules.has("sse"))
+        || (providers.jobs === "bullmq" && modules.has("bullmq"));
+    const usesObjectStorage = providers["object-storage"] === "s3"
+        && modules.has("object-storage-s3");
+    const usesEmbeddedProviders = providers.database === "sqlite"
+        || providers.cache === "memory"
+        || providers["object-storage"] === "local"
+        || providers.events === "memory"
+        || providers.jobs === "local";
     const usesAuth = modules.has("auth");
     const apiRequiredKeys = [
         ...(usesAuth ? ["BETTER_AUTH_SECRET"] : []),
@@ -311,7 +322,7 @@ function initializeDeploymentProfile(projectRoot, name, options) {
         },
         workloads: {
             api: {
-                replicas: 2,
+                replicas: usesEmbeddedProviders ? 1 : 2,
                 resources: {
                     cpuRequest: "250m",
                     cpuLimit: "1000m",
@@ -328,7 +339,7 @@ function initializeDeploymentProfile(projectRoot, name, options) {
                     memoryLimit: "1Gi",
                 },
             },
-            worker: modules.has("bullmq")
+            worker: providers.jobs === "bullmq" && modules.has("bullmq")
                 ? {
                     replicas: 1,
                     resources: {
@@ -342,7 +353,7 @@ function initializeDeploymentProfile(projectRoot, name, options) {
         },
         dependencies: {
             postgres: {
-                mode: "inCluster",
+                mode: usesPostgres ? "inCluster" : "disabled",
                 image: "postgres:16.10-alpine",
                 secretName: `${releaseName}-postgres`,
                 storageClassName: "",
@@ -357,8 +368,8 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             },
             objectStorage: {
                 mode: usesObjectStorage ? "inCluster" : "disabled",
-                image: "quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z",
-                clientImage: "quay.io/minio/mc:RELEASE.2025-08-13T08-35-41Z",
+                image: "pgsty/silo:RELEASE.2026-09-16T00-00-00Z",
+                clientImage: "pgsty/mc:RELEASE.2026-09-16T00-00-00Z",
                 secretName: `${releaseName}-object-storage`,
                 storageClassName: "",
                 storageSize: "8Gi",
@@ -379,7 +390,6 @@ function initializeDeploymentProfile(projectRoot, name, options) {
             ADDRESS_HEADER: "x-forwarded-for",
             XFF_DEPTH: "1",
             ...(usesAuth ? { BETTER_AUTH_URL: `https://${host}` } : {}),
-            ...(modules.has("sse") && usesRedis ? { SSE_TRANSPORT: "redis" } : {}),
             ...(modules.has("rate-limit")
                 ? {
                     RATE_LIMIT_TTL: "60",