docker-compose to Podman Quadlet Migration Prompt
Convert a docker-compose stack into Podman Quadlet systemd unit files with correct dependency ordering, networks, volumes, and rootless-safe port publishing.
- Target user
- Platform engineers replacing docker-compose with rootless Podman managed by systemd
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT
The prompt
You are a senior Linux platform engineer who has migrated real docker-compose stacks to Podman Quadlet. You know Quadlet is not a compose runtime: each service becomes a `.container` file, shared networks become `.network` files, named volumes become `.volume` files, and `depends_on` becomes systemd ordering rather than a compose keyword. You know generated units are named `<name>-<type>.service` (a `web.container` produces `web.service`), that rootless units live in `~/.config/containers/systemd/` and system units in `/etc/containers/systemd/`, and that `systemctl --user daemon-reload` is what regenerates them. I will give you a docker-compose file and the target environment. Convert it to a working Quadlet unit set. Steps: 1. **Inventory the stack**: list every service, network, volume, secret, and env file in the compose file, and mark anything Quadlet has no direct equivalent for (build contexts, `profiles`, `extends`, healthcheck-based `depends_on: condition: service_healthy`). 2. **Emit one .container per service**: map `image` to `Image=`, `ports` to `PublishPort=`, `environment` to `Environment=`, `env_file` to `EnvironmentFile=`, `command` to `Exec=`, `volumes` to `Volume=`, and `user` to `User=` — keep names stable with `ContainerName=`. 3. **Model networks and volumes as units**: create `.network` and `.volume` files for anything compose declared, and reference them from containers as `Network=stack.network` and `Volume=data.volume:/path`, noting that Quadlet resolves those to the generated unit dependencies automatically. 4. **Translate depends_on into systemd**: express ordering with `After=` and `Requires=`/`Wants=` in `[Unit]`, and be explicit that systemd ordering means "started", not "ready" — if the app needs readiness, propose a healthcheck plus `Notify=` or an app-level retry instead of pretending ordering is enough. 5. **Make it rootless-safe**: flag any published port below 1024, any bind mount that will need SELinux labeling, and any `user: root` assumption; suggest `net.ipv4.ip_unprivileged_port_start` or a high port plus a reverse proxy rather than running the stack as root. 6. **Handle build sections**: for services with `build:`, either point to a prebuilt image or use a `.build` file (Podman 5.0+) / an out-of-band `podman build`, and say which you chose and why. 7. **Set lifecycle policy**: add `[Service] Restart=on-failure` (or `always`) and a realistic `TimeoutStartSec=` for slow-pulling images, plus `[Install] WantedBy=default.target` so the stack comes back after reboot — and mention `loginctl enable-linger` for rootless units that must survive logout. 8. **Give the cutover procedure**: the exact sequence to stop the compose stack, place the files, reload, start, and verify, plus how to roll back to compose if it fails. Fill in: - docker-compose.yml: [PASTE] - Rootless or root Podman: [rootless / root] - Podman version: [VERSION] - Host OS and whether SELinux is enforcing: [DESCRIBE] Output as: (a) the complete set of Quadlet unit files with filenames and target directory, (b) a compose-key to Quadlet-directive mapping table including anything that could not be translated, and (c) the ordered cutover and verification commands. Do not silently drop compose features you cannot translate — list them explicitly as gaps. Test the generated units on a non-production host first, since `daemon-reload` failures in Quadlet surface as missing services rather than loud errors.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
The most common way a compose-to-Quadlet migration goes wrong is treating Quadlet as a drop-in compose replacement. Compose is a single orchestrator that reads one file and owns the whole stack; Quadlet is a systemd generator that turns each declaration into an independent unit. That difference shows up immediately in depends_on, which people expect to carry readiness semantics it never had even in compose. This prompt forces the distinction into step four, requiring the model to say plainly that After= means “started” and to propose a healthcheck or retry when the application actually needs readiness — which prevents a stack that comes up in the wrong order every third reboot.
The rootless-safety step exists because compose files are almost always written against rootful Docker and carry assumptions that quietly break. A ports: 80:80 line that worked under Docker fails outright for a rootless user unless net.ipv4.ip_unprivileged_port_start has been lowered, and bind mounts that Docker happily accepted will be unreadable to the container on an SELinux-enforcing host. Surfacing those before cutover turns a confusing post-migration outage into a two-line configuration decision made up front.
Requiring an explicit gap list is what keeps the output honest. Build contexts, profiles, and extends have no clean Quadlet equivalent, and a model asked to “convert this” will otherwise invent plausible-looking directives to fill the hole. By making unmapped features a required deliverable alongside the units themselves, the prompt produces a migration you can actually review — you see what moved, what changed shape, and what still needs a human decision, with a documented rollback to compose if the cutover goes badly.
Related prompts
-
Docker to Podman Team Migration Plan Prompt
Produce a phased Docker-to-Podman migration plan covering socket compatibility, CI impact, rootless gaps, and the developer workflow changes a team will actually hit.
-
Podman systemd Auto-Update and Unit Hardening Prompt
Configure podman auto-update with safe rollback, correct restart policy, and systemd unit hardening for containers managed as Quadlet services.
-
Podman Healthcheck Design for systemd Prompt
Design container healthchecks that genuinely detect failure under Podman, including startup probes, on-failure actions, and correct interaction with systemd restart policy.
-
Podman Host Drift & Storage Reclamation Audit Prompt
Audit a running Podman host for configuration drift from its declared units, orphaned images and containers, and reclaimable storage, then produce a safe cleanup plan.
More Podman prompts & error guides
Browse every Podman prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.