Skip to content
🎉 Launch sale:50% off everything over $22 — automatically applied at checkout· ends Aug 2Shop the sale →
DevOps AI ToolKit
Newsletter
All prompts
AI for Podman Difficulty: Intermediate ClaudeChatGPT

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

More Podman prompts & error guides

Browse every Podman prompt and troubleshooting guide in one place.

Free download · 368-page PDF

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.