mirror of
https://github.com/containers/podman.git
synced 2025-09-21 03:35:06 +08:00
219 lines
4.3 KiB
Markdown
219 lines
4.3 KiB
Markdown
% 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`
|
|
|
|
```ini
|
|
[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:
|
|
```bash
|
|
mkdir -p ~/.config/containers/systemd
|
|
cp hello.container ~/.config/containers/systemd/
|
|
```
|
|
|
|
For rootful use:
|
|
```bash
|
|
sudo cp hello.container ~/etc/containers/systemd/
|
|
```
|
|
|
|
## Step 3: Reload and enable the service
|
|
|
|
For rootless use:
|
|
```bash
|
|
systemctl --user daemon-reload
|
|
systemctl --user start hello.service
|
|
```
|
|
|
|
For rootful use:
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now hello.service
|
|
```
|
|
|
|
## Expected Output:
|
|
|
|
For rootles, check logs using:
|
|
```bash
|
|
journalctl --user -u hello.service
|
|
```
|
|
|
|
For rootful:
|
|
```bash
|
|
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`
|
|
|
|
```ini
|
|
[Volume]
|
|
VolumeName=mydata
|
|
Label=purpose=demo
|
|
```
|
|
|
|
## Step 2: Place and reload
|
|
|
|
For rootless use:
|
|
```bash
|
|
mkdir -p ~/.config/containers/systemd
|
|
cp mydata.volume ~/.config/containers/systemd/
|
|
systemctl --user daemon-reload
|
|
```
|
|
|
|
For rootful use:
|
|
```bash
|
|
sudo cp mydata.volume /etc/containers/systemd/
|
|
sudo systemctl daemon-reload
|
|
```
|
|
|
|
## Step 3: Create the volume
|
|
|
|
For rootless use:
|
|
```bash
|
|
systemctl --user start mydata-volume.service
|
|
```
|
|
|
|
For rootful use:
|
|
```bash
|
|
systemctl start mydata-volume.service
|
|
```
|
|
|
|
# EXAMPLE 3: CONTAINER USING A VOLUME
|
|
|
|
## Create `with-volume.container`
|
|
|
|
```ini
|
|
[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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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`
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=Nginx Webserver
|
|
|
|
[Container]
|
|
Image=nginx:alpine
|
|
PublishPort=8080:80
|
|
|
|
[Install]
|
|
WantedBy=default.target
|
|
```
|
|
|
|
## Start the web server
|
|
|
|
For rootless use:
|
|
```bash
|
|
cp webserver.container ~/.config/containers/systemd/
|
|
systemctl --user daemon-reload
|
|
systemctl --user start webserver.service
|
|
```
|
|
|
|
For rootful use:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
systemd-analyze --user --generators=true verify foo.service
|
|
```
|
|
|
|
# SEE ALSO
|
|
|
|
[podman-quadlet(7)](podman-quadlet.7.md),
|
|
[podman-container.unit(5)](podman-container.unit.5.md),
|
|
[podman-volume.unit(5)](podman-volume.unit.5.md),
|
|
[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)
|
|
|
|
# AUTHORS
|
|
|
|
Podman Team <https://podman.io>
|