Turn Containers Into Systemd Services with Podman: A Practical Guide

Concrete Problem: Running Containers as Reliable Services

When a container hosts a critical service—web server, database, or background worker—you want the same guarantees that systemd offers for native binaries: automatic restarts, dependency ordering, logging, and offline configuration. Without a wrapper, you must script the container start, handle failures, and manually enable restart policies.

Podman provides a built‑in way to bridge this gap by generating .service files that describe the container exactly as you would start it with podman run. This blog walks through that feature, shows how to use it for both rootless users and pods, and highlights the trade‑offs to keep in mind.

Generating a Systemd Unit for a Single Container

Assume you have an image ghcr.io/example/myapp:latest that you normally run with:

podman run --name myapp \
  -p 8080:80 \
  -e "ENV=prod" \
  ghcr.io/example/myapp:latest

To turn this into a systemd service, use:

podman generate systemd \
  --name myapp \
  --files \
  --restart unless-stopped \
  --port 8080:80 \
  --env ENV=prod \
  ghcr.io/example/myapp:latest

The command writes myapp.service (and optionally myapp.socket if you used --publish-all) into the current directory. The file contains a complete ExecStart line that pulls the image if it’s missing, creates the container, and starts it.

Inspecting the Generated Unit

Open the file to see the mapping:

[Unit]
Description=Podman container myapp
After=network.target

[Service]
Restart=unless-stopped
ExecStartPre=/usr/bin/podman pull ghcr.io/example/myapp:latest
ExecStart=/usr/bin/podman start --attach myapp
ExecStop=/usr/bin/podman stop --time=10 myapp

[Install]
WantedBy=default.target

Key points:

• Restart=unless-stopped gives the same semantics as --restart unless-stopped.
• Systemd’s dependency handling (After=network.target) ensures the container only starts when the network is ready.
• The ExecStartPre step pulls the image if it isn’t already present.

Enabling and Running the Service

For a root‑based system:

sudo mv myapp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now myapp.service

Verify:

systemctl status myapp.service
journalctl -u myapp.service -f

For a rootless user, podman places the unit in ~/.config/systemd/user/ and starts the user instance:

mkdir -p ~/.config/systemd/user
mv myapp.service ~/.config/systemd/user/
loginctl enable-linger $USER
systemctl --user daemon-reload
systemctl --user enable --now myapp.service

Rootless units require that the user has a running user‑systemd instance. On a headless server, loginctl enable-linger keeps the user unit active after logout.

Customizing the Unit After Generation

Podman’s generator is just a starting point. You can add environment variables, change restart policies, or tweak the network namespace:

# Add a custom environment variable
Environment=MY_VAR=hello

# Override the restart policy
Restart=always
RestartSec=5

# Bind mount a host directory
Mounts=/host/data:/data:Z

After editing, run systemctl daemon-reload to apply changes.

Managing a Group of Containers with Pods

Podman pods let you treat several containers as a single logical unit. Generate a unit for a pod with:

podman pod create --name mypod
podman pod add --name mypod myapp
podman generate systemd --name mypod --files

The resulting mypod.service starts all containers in the pod together. This is useful for multi‑service applications where the containers must share a network namespace or shared volumes.

Using Timers to Schedule Container Runs

Systemd timers can trigger containers on a schedule. Generate a timer with:

podman generate systemd --name myapp --timer --files

Move the myapp.timer and myapp.service to /etc/systemd/system/, then enable the timer:

sudo systemctl enable --now myapp.timer

Systemd will start the container at the scheduled times, and the service file ensures proper logging and restart behavior.

Trade‑offs and Limitations

• Only works on Linux hosts that use systemd; other init systems (SysV, Upstart, OpenRC) cannot consume the generated units.
• Rootless units need a user‑systemd instance and may fail on headless servers unless loginctl enable-linger is run.
• Complex networking (custom bridges, host networking) isn’t automatically configured; manual edits to ExecStart or Mounts may be required.
• Podman version differences can change the unit format; scripts that rely on specific directives should test against the target Podman release.
• If the image isn’t present locally, the unit’s ExecStartPre pulls it, but a network failure during this step will prevent the service from starting.

Actionable Next Steps

1. Identify the container you want to run as a service and note its run options.
2. Generate a unit with podman generate systemd, adding any extra flags you need.
3. Move the unit to /etc/systemd/system/ (root) or ~/.config/systemd/user/ (rootless).
4. Reload systemd, enable, and start the service.
5. Verify with systemctl status and journalctl -u.
6. Optional: create a timer if you need scheduled runs.
7. Commit the unit file to version control and deploy it to production hosts for consistent lifecycle management.

By following these steps, you give your containers the same reliability, observability, and lifecycle controls as native systemd services, while keeping the flexibility of Podman’s container model.