podman-quadlet-basic-usage(7)

NAME
podman-quadlet-basic-usage - Basic usage examples and step-by-step guide for Podman Quadlet

DESCRIPTION
This guide introduces common usage patterns for Podman Quadlet. It provides step-by-step examples for defining containers, exposing ports, creating volumes, and establishing dependencies using declarative .container, .volume, and related unit files.

Quadlet simplifies container lifecycle management by translating these files into systemd services, making them manageable with systemctl.

EXAMPLE 1: RUNNING A SIMPLE CONTAINER

Step 1: Create hello.container
    [Unit]
    Description=Hello Alpine Container
    [Container]
    Image=alpine
    Exec=echo Hello from Quadlet!
    [Install]
    WantedBy=multi-user.target

Step 2: Place the file
For rootless use:
    mkdir -p ~/.config/containers/systemd
    cp hello.container ~/.config/containers/systemd/

For rootful use:
    sudo cp hello.container /etc/containers/systemd/

Step 3: Reload and start the service
For rootless use:
    systemctl --user daemon-reload
    systemctl --user start hello.service

For rootful use:
    sudo systemctl daemon-reload
    sudo systemctl start hello.service

Note quadlet services cannot be enabled as they are a generated systemd unit, see podman-systemd.unit(5) for more information.

Expected Output:
For rootless, check logs using:
    journalctl --user -u hello.service

For rootful:
    journalctl -u hello.service

You should see: Hello from Quadlet!

That means the container started, executed the echo command, and exited.

EXAMPLE 2: CREATING A NAMED VOLUME

Step 1: Create mydata.volume
    [Volume]
    VolumeName=mydata
    Label=purpose=demo

Step 2: Place and reload
For rootless use:
    mkdir -p ~/.config/containers/systemd
    cp mydata.volume ~/.config/containers/systemd/
    systemctl --user daemon-reload

For rootful use:
    sudo cp mydata.volume /etc/containers/systemd/
    sudo systemctl daemon-reload

Step 3: Create the volume
For rootless use:
    systemctl --user start mydata-volume.service

For rootful use:
    systemctl start mydata-volume.service

EXAMPLE 3: CONTAINER USING A VOLUME

Create with-volume.container
    [Unit]
    Description=Container with Mounted Volume
    [Container]
    Image=alpine
    Exec=sh -c "ls /data && echo Hello > /data/hello.txt"
    Volume=mydata.volume:/data
    [Install]
    WantedBy=multi-user.target

This container lists all files in the volume and creates hello.txt.

Start the container and check the status
For rootless use:
    cp with-volume.container ~/.config/containers/systemd/
    systemctl --user daemon-reload
    systemctl --user start with-volume.service
    systemctl --user status with-volume.service

For rootful use:
    sudo cp with-volume.container /etc/containers/systemd/
    sudo systemctl daemon-reload
    sudo systemctl start with-volume.service
    sudo systemctl status with-volume.service

When started for the first time, the hello.txt will not appear in the systemctl status output, because it has not been created yet. But when started for the second time, the output will be:
    hello.txt

This means the volume is used and is persistent.

EXAMPLE 4: EXPOSING A CONTAINER PORT TO THE HOST

Create webserver.container
    [Unit]
    Description=Nginx Webserver
    [Container]
    Image=nginx:alpine
    PublishPort=8080:80
    [Install]
    WantedBy=multi-user.target

Start the web server
For rootless use:
    cp webserver.container ~/.config/containers/systemd/
    systemctl --user daemon-reload
    systemctl --user start webserver.service

For rootful use:
    sudo cp webserver.container /etc/containers/systemd/
    sudo systemctl daemon-reload
    sudo systemctl start webserver.service

Visit http://localhost:8080 in your browser.

TIPS
To start a container on system boot, use:
    [Install]
    WantedBy=multi-user.target

If systemctl cannot find foo.service, it usually means there is a syntax error in your Quadlet file. To find the details, use:
    systemd-analyze --user --generators=true verify foo.service

SEE ALSO
podman-systemd.unit(5), podman-container.unit(5), podman-volume.unit(5), systemd.unit(5)

AUTHORS
Podman Team ⟨https://podman.io⟩