4.3 KiB
% 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 enable the service
For rootless use:
systemctl --user daemon-reload
systemctl --user start hello.service
For rootful use:
sudo systemctl daemon-reload
sudo systemctl enable --now hello.service
Expected Output:
For rootles, 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 statement 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=default.target
This container shows all the files on volume and creates the 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: EXPOSE CONTAINER PORT TO HOST
Create webserver.container
[Unit]
Description=Nginx Webserver
[Container]
Image=nginx:alpine
PublishPort=8080:80
[Install]
WantedBy=default.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 ~/.config/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 default.target
If the foo.service file is not generated, 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-quadlet(7), podman-container.unit(5), podman-volume.unit(5), systemd.unit(5)
AUTHORS
Podman Team https://podman.io