.nh
.TH podman-quadlet-basic-usage 7

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


.SH 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 \fB\&.container\fR, \fB\&.volume\fR,
and related unit files.

.PP
Quadlet simplifies container lifecycle management by translating these files into systemd services, making them
manageable with \fBsystemctl\fR\&.


.SH EXAMPLE 1: RUNNING A SIMPLE CONTAINER
.SH Step 1: Create \fBhello.container\fR
.EX
[Unit]
Description=Hello Alpine Container

[Container]
Image=alpine
Exec=echo Hello from Quadlet!

[Install]
WantedBy=multi-user.target
.EE

.SH Step 2: Place the file
For rootless use:

.EX
mkdir -p ~/.config/containers/systemd
cp hello.container ~/.config/containers/systemd/
.EE

.PP
For rootful use:

.EX
sudo cp hello.container /etc/containers/systemd/
.EE

.SH Step 3: Reload and start the service
For rootless use:

.EX
systemctl --user daemon-reload
systemctl --user start hello.service
.EE

.PP
For rootful use:

.EX
sudo systemctl daemon-reload
sudo systemctl start hello.service
.EE

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

.SH Expected Output:
For rootless, check logs using:

.EX
journalctl --user -u hello.service
.EE

.PP
For rootful:

.EX
journalctl -u hello.service
.EE

.PP
You should see: \fBHello from Quadlet!\fR

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


.SH EXAMPLE 2: CREATING A NAMED VOLUME
.SH Step 1: Create \fBmydata.volume\fR
.EX
[Volume]
VolumeName=mydata
Label=purpose=demo
.EE

.SH Step 2: Place and reload
For rootless use:

.EX
mkdir -p ~/.config/containers/systemd
cp mydata.volume ~/.config/containers/systemd/
systemctl --user daemon-reload
.EE

.PP
For rootful use:

.EX
sudo cp mydata.volume /etc/containers/systemd/
sudo systemctl daemon-reload
.EE

.SH Step 3: Create the volume
For rootless use:

.EX
systemctl --user start mydata-volume.service
.EE

.PP
For rootful use:

.EX
systemctl start mydata-volume.service
.EE


.SH EXAMPLE 3: CONTAINER USING A VOLUME
.SH Create \fBwith-volume.container\fR
.EX
[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
.EE

.PP
This container lists all files in the volume and creates \fBhello.txt\fR\&.

.SH Start the container and check the status
For rootless use:

.EX
cp with-volume.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start with-volume.service
systemctl --user status with-volume.service
.EE

.PP
For rootful use:

.EX
sudo cp with-volume.container /etc/containers/systemd/
sudo systemctl daemon-reload
sudo systemctl start with-volume.service
sudo systemctl status with-volume.service
.EE

.PP
When started for the first time, the \fBhello.txt\fR will not appear in the
\fBsystemctl status\fR output, because it has not been created yet. But when
started for the second time, the output will be:

.EX
hello.txt
.EE

.PP
This means the volume is used and is persistent.


.SH EXAMPLE 4: EXPOSING A CONTAINER PORT TO THE HOST
.SH Create \fBwebserver.container\fR
.EX
[Unit]
Description=Nginx Webserver

[Container]
Image=nginx:alpine
PublishPort=8080:80

[Install]
WantedBy=multi-user.target
.EE

.SH Start the web server
For rootless use:

.EX
cp webserver.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start webserver.service
.EE

.PP
For rootful use:

.EX
sudo cp webserver.container /etc/containers/systemd/
sudo systemctl daemon-reload
sudo systemctl start webserver.service
.EE

.PP
Visit \fBhttp://localhost:8080\fR in your browser.


.SH TIPS
To start a container on system boot, use:

.EX
[Install]
WantedBy=multi-user.target
.EE

.PP
If \fBsystemctl\fR cannot find \fBfoo.service\fR, it usually means there is a syntax
error in your Quadlet file. To find the details, use:

.EX
systemd-analyze --user --generators=true verify foo.service
.EE


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


.SH AUTHORS
Podman Team 
\[la]https://podman.io\[ra]