Flisk Import Compose

---
name: flisk-import-compose
description: Import an existing Docker Compose project into Flisk with `flisk import .` - it reads the root Compose file (docker-compose.yml/.yaml, compose.yml/.yaml) and writes one bring-your-own service.json per service, keeping images, builds, ports and their host address, volumes and their Docker names, healthchecks, depends_on conditions, command/entrypoint, env_file, tmpfs, limits, profiles and models. Then prove it on a real run before any PR. Use when a repo has a root Compose file and the user wants it under `flisk up`, or to propose Flisk to a project that uses Compose. For a single Dockerfile or image use flisk-byo; for a Procfile use flisk-import-procfile.
license: MIT
compatibility: Requires the flisk CLI 1.4.26 or later (the importer is the npm package flisk-import; FLISK_IMPORT_PACKAGE pins a version). Does not deploy. Does not start containers.
metadata:
  author: flisk-sh
  version: "1.1"
---

# Import Docker Compose into Flisk

`flisk import` reads the root Compose file and writes one bring-your-own `service.json` per service. `flisk export compose` writes a standalone Compose file back from those files, so a project can keep plain `docker compose` working.

## Workflow

1. From the repo root run `flisk import . --dry-run` and read every line under *Skipped / not fully imported* and every `note:`.
2. Run `flisk import . --yes` to write. Put the values it lists as missing into the project `.env` (never commit it).
3. `flisk doctor`, `flisk up <stack> --dry-run`, then `flisk up <stack>` for real.
4. Optional: `flisk export compose` writes `.autogenerated/docker-compose.yml`; run it with `docker compose --env-file .env -f .autogenerated/docker-compose.yml up -d` (Compose reads `.env` from the file's own folder otherwise). CI can run `flisk export compose --check`.

## What maps

- `image` → `image`; `build` → `buildContext` + `dockerfile`.
- `command` / `entrypoint` on an image → a small `Dockerfile` next to `service.json` (`FROM` the image + `CMD`/`ENTRYPOINT`).
- Ports: one HTTP port is routed; every other published port becomes `extraPorts` on the same host address as in Compose (`"80:80"` → `"bind": "0.0.0.0"`, `"127.0.0.1:5432:5432"` → loopback, another address or `${VAR:-default}` → `publish`).
- `volumes`: named volumes keep their Docker name (`volumes[].name`), so an existing install's data is reused; bind mounts stay inside the project.
- `healthcheck` → `healthCheck.command`; `depends_on` conditions → `dependsOn`; `restart` → `restart`.
- `env_file` → `envFile`; `tmpfs` → `container.tmpfs`; `deploy.resources.limits` → `container.cpus`/`container.memory`; `profiles` → `profiles` (`flisk up --profile`); `models` → `models`.
- Secrets and other non-literal values go to `secrets.required` and the project `.env`.

## Prove it before a PR

A dry run and a green CI badge are not evidence. Before proposing the change to a project, follow flisk-convert step 5. The reference is the self-review on [biolend83/tubehaus#42](https://github.com/biolend83/tubehaus/pull/42#issuecomment-6556357152), which was merged:

- a real `flisk up` on the released Flisk the docs name, with fresh volumes or a throwaway project name (on Colima, run from under `$HOME`);
- screenshots of the app doing something real, the `flisk up` output, Tilt all green, and the changed service's logs, with the raw text under each;
- each migrated setting traced `.env` → `service.json` → generated Compose → `docker inspect`, and ports checked from outside (loopback vs the LAN address);
- a self-review comment: checked, fixed after review, behaviour changes, Flisk-side issues, not verified;
- Flisk offered as an option next to their Compose file, the same volume names, and disclosure that you work on Flisk and used an AI assistant.

## Guardrails

- Every `not written` and `not translated` line is a gap. If the result does not start the same stack, fix Flisk (the importer, the exporter or core), not the user's project.
- Never edit or delete the project's Compose file. Never overwrite an existing `service.json` without `--force`.
- Service names become kebab-case (`lychee_api` → `lychee-api`); check that other services still reach the old hostname.
- Does not start anything. Put secrets in `.env`, not in the plan output or a PR.