Docs

From Docker Compose

A product that ships as docker-compose.yml or compose.yaml, often run on one customer server, moves onto Alien with the same images. Each service becomes a container in alien.ts, and the stack deploys into the customer's cloud account, Kubernetes cluster, or Linux servers, with updates from every alien release.

From the repository that has your Compose file:

Bring this Compose app to Alien
Install the Alien skills: npx skills add alienplatform/skills Use the alien-integration skill to bring our Docker Compose install to Alien as a whole-product deployment, following https://alien.dev/docs/guide/existing-app/compose.md. Run docker compose config with the env file and profiles real installs use. Map every service, volume, healthcheck, depends_on, and one-shot service to alien.ts. Measure CPU and memory for services that set none. Never copy values from .env into code. Show me the mapping before writing alien.ts. Give every stateful service and setup step a health check that proves it's ready. Verify with alien dev, including a real login and the product's main action. Don't publish a release, create a customer deployment, or apply any infrastructure change without asking.

Render the file

Map the resolved file, with the env file and profiles your customers use:

docker compose --env-file .env.production --profile production config > rendered.yaml

config resolves extends, x- anchors, variables, and profiles. The .env file often holds plaintext passwords: each becomes a generated secret, and no value is copied into alien.ts.

An example

docker-compose.yml
services:
  migrate:
    image: ghcr.io/acme/api:2.3.0
    command: ["./migrate", "up"]
    depends_on:
      db: { condition: service_healthy }
  api:
    image: ghcr.io/acme/api:2.3.0
    ports: ["80:8080"]
    environment:
      DATABASE_URL: postgres://acme:${DB_PASSWORD}@db:5432/acme
    depends_on:
      migrate: { condition: service_completed_successfully }
  redis:
    image: redis:7
    command: ["redis-server", "--appendonly", "yes"]
    volumes: ["redis-data:/data"]
  db:
    image: postgres:17
volumes:
  redis-data:
alien.ts
import * as alien from "@alienplatform/core"

// Was the db service. Its password from .env is no longer needed:
// the link provides the connection.
const db = new alien.Postgres("db").build()

// Was the redis service and its named volume.
const redis = new alien.Container("redis")
  .code({ type: "image", image: "redis:7" })
  .command(["redis-server", "--appendonly", "yes"])
  .cpu(0.5)
  .memory("1Gi")
  .port(6379)
  .persistentStorage("10Gi", { mountPath: "/data" })
  .permissions("redis")
  .build()

// Was the api service. The one-shot migrate service now runs before the server
// starts. A launcher sets DATABASE_URL from the db link.
const api = new alien.Container("api")
  .code({ type: "image", image: "ghcr.io/acme/api:2.3.0" })
  .command(["sh", "-c", "./migrate up && exec ./server"])
  .cpu(1)
  .memory("2Gi")
  .port(8080)
  .publicEndpoint("app", 8080, "http")
  .healthCheck({ path: "/ready", failureThreshold: 10 })
  .link(db)
  .link(redis)
  .permissions("api")
  .build()

export default new alien.Stack("acme")
  .add(db, "frozen")
  .add(redis, "live")
  .add(api, "live")
  .permissions({
    profiles: {
      api: { db: ["postgres/data-access"] },
      redis: {},
    },
  })
  .build()

The app still reads DATABASE_URL. See Images that don't use the Alien SDK for the launcher that sets it.

Mapping

Composealien.ts
Service with imageA Container with .code({ type: "image", image })
Service with build.code({ type: "source", src, toolchain: { type: "docker" } })
command, entrypoint.command([...]): the entrypoint first, then the command
environment, env_file.environment({...}) for plain values, inputs and secrets for the rest
ports, expose.port(containerPort). The host port has no meaning.
A port users open in a browser.publicEndpoint(name, port, "http")
Named volume.persistentStorage(size, { mountPath })
Bind mount of a config fileA thin image built on yours, or a file rendered from env at start
healthcheck.healthCheck({ path, port, failureThreshold }). Health checks are HTTP; a CMD test needs a small readiness endpoint.
depends_on with service_started or service_healthy.link() on that service, and retry on startup
depends_on with service_completed_successfullyThe dependency is a setup step: a command, or the start of one service's command
A one-shot serviceA Container with commands, or idempotent steps at the start of one service's command
deploy.replicas.replicas(n)
deploy.resources.cpu() and .memory()
secrets read through *_FILE variablesAn input. A launcher writes it to a private file and sets *_FILE.
user, read_only.security({ profile: "restricted", runAsUser, runAsGroup, readOnlyRootFilesystem })
security_opt, cap_add, pids_limitNo equivalent. Move untrusted code into a Sandbox, or record the gap.
restart, container_name, loggingDrop them: Alien restarts containers and collects their logs.
networksDrop them: services in a stack are private. An internal network behind an egress proxy is a security control: use .egress("internet"), or record the gap.

Details to check

  • CPU and memory. Compose files rarely set them, and alien.ts requires both. Measure each service under real use with docker stats and add headroom.
  • Host access. network_mode: host, privileged, devices, and mounts of host paths such as /var/run/docker.sock need a Daemon, which runs on the host, not a Container.
  • Start order. Compose starts services in an order the file doesn't fully state. Write it down, then make each setup step safe to run again.
  • Image tags. A pinned tag that fails to docker pull usually means the pin is wrong.

Next

On this page