Skip to content
Isoloom

Guides

Import from Compose

Draft an isoloom.yml from a Docker Compose file, with a note for everything Compose says that the draft doesn't.

Most environments already exist as a Compose file. isoloom import compose turns one into a draft isoloom.yml:

isoloom import compose docker-compose.yml

It writes isoloom.yml next to the Compose file (--stdout prints it instead, --force replaces an existing one), then lists every key it didn't carry over, and why. The verdicts come from the coverage table, so the import and the table always agree.

What it carries over

ComposeBecomes
namename, as kebab-case
networks, ipam subnetnetworks with that cidr (re-addressed into 10.88.x.0/24 when it isn't a /24 to /29 in 10.0.0.0/8)
internal: trueinternet: false
ipv4_addressthe machine's address on that network (its last octet)
ports, exposeservices: the container ports; a fixed host port becomes publish (on the loopback)
environment values read from the shell (${TOKEN})inputs, on the spec and the machine
deploy.resources.limits, cpus, mem_limitresources
depends_ondepends_on, when the dependency has a port to wait for
image, builddocker: { image } or docker: { build }

What it reports

NoteMeaning
Changed on the way inRenamed, re-addressed, or left out: check these first
Belongs in the imageFixed environment values, commands, mounted project files: move them into the image (or a docker.init job)
Not expressible yetEvery VM target could do it, the format doesn't yet: shared volumes, ulimits, DNS
Same effect another wayhealthcheck (Isoloom probes every port), hostname (the machine's name)
Left out: not every target can do itContainer-only settings like privileged or cap_drop, CPU scheduling knobs
Compose toolingprofiles, links, x- extensions: nothing to carry over

Two kinds of services are left out of the draft on purpose, with a note:

  • Jobs that run once (others wait for them with service_completed_successfully). Isoloom machines stay up and restart, so a job would run forever. One-shot work is a docker.init job of the machine it prepares.
  • Profile-only services, which Compose doesn't start by default. A tester belongs in checks:.

When a name has to change (wazuh.manager isn't a DNS label), the note says which services still use the old name in their environment.

An example

# docker-compose.yml
name: Shop_Demo
services:
  web:
    image: nginx:1.27-alpine
    ports: ["8080:80"]
    environment:
      API_TOKEN: ${API_TOKEN}
      MODE: production
    depends_on:
      cache: { condition: service_healthy }
      seed: { condition: service_completed_successfully }
    networks:
      front: { ipv4_address: 172.30.1.10 }
      back: {}
    deploy: { resources: { limits: { cpus: "0.5", memory: 256M } } }
  cache:
    image: redis:7-alpine
    expose: ["6379"]
    networks: [back]
    volumes: ["cache-data:/data"]
  seed:
    image: redis:7-alpine
    command: redis-cli -h cache set greeting hello
    depends_on: { cache: { condition: service_healthy } }
    networks: [back]
networks:
  front:
    ipam: { config: [{ subnet: 172.30.1.0/24 }] }
  back:
    internal: true
    ipam: { config: [{ subnet: 10.31.2.0/24 }] }
volumes:
  cache-data: {}

The draft:

version: 1
name: shop-demo

networks:
  front: { cidr: 10.88.1.0/24 }
  back:  { cidr: 10.31.2.0/24, internet: false }

inputs: [API_TOKEN]

machines:
  web:
    networks: { front: 10, back: 10 }
    services: [{ port: 80 }]
    inputs: [API_TOKEN]
    resources: { cpus: 1, memory_mb: 256 }
    depends_on: [cache]
    docker:
      image: "nginx:1.27-alpine"

  cache:
    networks: { back: 11 }
    services: [{ port: 6379 }]
    docker:
      image: "redis:7-alpine"

And the notes: front re-addressed, seed left out (a one-shot job), MODE=production belongs in the image, the cache-data volume isn't expressible yet, and the published port 8080 is kept on the loopback. The full version of this file (with a healthcheck and a profile-only tester) runs in Isoloom's CI: imported, generated and started, the draft behaves like the original.

Then

  1. Work through the notes, starting with Changed on the way in.
  2. Add vm: to each machine for the VM targets (Spec reference).
  3. Add checks that prove the behavior, and isoloom generate.