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:
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.yamlconfig 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
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: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
| Compose | alien.ts |
|---|---|
Service with image | A 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 file | A 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_successfully | The dependency is a setup step: a command, or the start of one service's command |
| A one-shot service | A 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 variables | An 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_limit | No equivalent. Move untrusted code into a Sandbox, or record the gap. |
restart, container_name, logging | Drop them: Alien restarts containers and collects their logs. |
networks | Drop 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.tsrequires both. Measure each service under real use withdocker statsand add headroom. - Host access.
network_mode: host,privileged,devices, and mounts of host paths such as/var/run/docker.sockneed 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 pullusually means the pin is wrong.
Next
- Bring an existing app: images, launchers, and verification.
- Linux servers: deploying onto the customer's own machines.