What are Quadlets?

In this post I’ll show you what a quadlet is and how you can use it to manage your containers.

Quadlets are a new way to manage containers using systemd. They are a new format for systemd units that allow you to manage containers using systemd.

Container Quadlets

Here’s an example of a container quadlet.

[Container]
Image=docker.io/library/alpine:latest
Exec=sleep infinity
AutoUpdate=registry

If you put this in ~/.config/containers/systemd/alpine.container you can start it with systemctl --user start alpine and it will start a new container.

Just make sure to systemctl --user daemon-reload to reload the systemd daemon after you create the quadlet. You have to do this every time, I won’t repeat this throughout the blog post.

Pod Quadlets

You can also use quadlets to manage pods. Here’s an example of a pod quadlet.

[Pod]

Yep, that’s it. If you put it in ~/.config/containers/systemd/mypod.pod you can start it with systemctl --user start mypod-pod and it will start a new pod.

But the best part is this. If you want to add a container to a pod all you have to do is this.

[Container]
Image=docker.io/library/alpine:latest
Exec=sleep infinity
AutoUpdate=registry
Pod=mypod.pod

Now when you start mypod-pod it will start the container as well.

Dependencies

You can add dependencies.

[Unit]
After=alpine.service

[Container]
Image=docker.io/library/archlinux:latest
Exec=sleep infinity
AutoUpdate=registry
Pod=mypod.pod

Now archlinux will start after alpine.

There are even more options. You can start .kube, .network, and .build quadlets too and they can depend on each other. See the docs for more info!

Example: Nginx and Certbot

Okay so now lets run something useful :)

How about an nginx container and a certbot container to get a certificate for it?

Nginx Container

First lets create a directory to hold our files.

mkdir -p ~/.config/containers/systemd/www

Next we create a quadlet for our nginx container.

[Container]
Image=docker.io/nginx:latest
PublishPort=80:80
PublishPort=443:443
AutoUpdate=registry
Volume=./www:/usr/share/nginx/html

This will run a web server for us. If you aren’t root, you’ll need to enable unprivleged ports.

sudo sysctl net.ipv4.ip_unprivileged_port_start=0

Now we can start it with systemctl --user start nginx and it will start a new container.

If you browse to http://localhost you should see the nginx welcome page.

Certbot Container

Now we need to get a certificate for it. We can use certbot for this.

[Container]
Image=docker.io/certbot/certbot:latest
Volume=letsencrypt:/etc/letsencrypt
Volume=./www:/mnt
Exec=certonly --webroot --webroot-path /mnt --agree-tos --email your@email.com -d your.domain.com
AutoUpdate=registry

Make sure to replace your@email.com and your.domain.com with your own email and domain.

Then start the container with systemctl --user start certbot and it will get a certificate for you.

Nginx with SSL

Now you can use the certificate in your nginx container.

[Container]
Image=docker.io/nginx:latest
PublishPort=80:80
PublishPort=443:443
AutoUpdate=registry
Volume=letsencrypt:/etc/letsencrypt

That’s great, but now we need to configure nginx to use the certificate. We can do this by adding a volume for the configuration file.

[Container]
Image=docker.io/nginx:latest
PublishPort=80:80
PublishPort=443:443
AutoUpdate=registry
Volume=letsencrypt:/etc/nginx/certs
Volume=./nginx.conf:/etc/nginx/conf.d

Along with a configuration file for nginx.

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /etc/nginx/certs/live/your.domain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/live/your.domain.com/privkey.pem;

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }
}

Again, make sure to replace your.domain.com with your own domain.

Now you can start the container with systemctl --user start nginx and it will start a new container with the certificate. You can verify this by going to https://your.domain.com.

Now you have a web server with HTTPS.

Automatic Certificate Renewal

If you want to renew your certificate automatically it’s as simple as this.

[Container]
Image=docker.io/certbot/certbot:latest
Exec=renew
AutoUpdate=registry
Volume=letsencrypt:/etc/letsencrypt

Now you can create a timer for it in ~/.config/systemd/user/certbot.timer.

[Unit]
Description=Renew Certbot certificates

[Timer]
OnCalendar=Sun 00:00:00
Persistent=true
Unit=certbot.service

[Install]
WantedBy=timers.target

Now you enable the timer.

systemctl --user enable --now certbot.timer

Now your certificate will be renewed every Sunday at midnight.

That’s it! Now you have a web server with HTTPS and a certificate that will be renewed automatically.

Introduction

X11Docker is a nice command line tool that allows you to run graphical applications inside podman or docker by passing them to xpra or your wayland socket. To do this you first need a Containerfile or Dockerfile to build an image with the application you want to run. In this example I’m going to run telegram-desktop.

Building a Container Image

FROM ubuntu:latest

RUN apt-get update
RUN apt-get install -y telegram-desktop

CMD ["telegram-desktop"]

Running the Application with X11Docker

We build this image with podman build . -t telegram and wait for it to install our packages. When it’s done we can simply run it with x11docker localhost/telegram and it starts Telegram in Xpra.

Running with Wayland

If we wanted to start it under Wayland instead, we could run x11docker --wayland localhost/telegram however the package for Telegram on Ubuntu doesn’t seem to have support for Wayland when I tried it.

This should work for any graphical software, even that which isn’t in the repositories. You can even install more than one piece of software in a single image. Then you pass the CMD as an argument to x11docker like so x11docker localhost/telegram telegram-desktop.

Introduction

Podman^1 has a nice feature called generate that lets you generate different kinds of configuration files for starting pods. One that I use often is podman generate systemd which generates a new user service that can be started with systemctl --user start container-yourcontainer.service or enabled.

Auto-Updating Containers

If you want your container to auto update you can simply pass it the flag --label "io.containers.autoupdate=registry" when you’re creating it. The systemd service will automatically pull the latest versions of containers before starting them. You can manually update your container images now using podman auto-update.

If you want to update your images on a schedule you can enable the podman-auto-update.timer using systemctl --user enable --now podman-auto-update.timer which will auto update your containers every Monday morning.^2

Kubernetes YAML Generation

You can also generate a Kubernetes YAML configurations using podman generate kube. This can then be loaded in Kubernetes to run your containers.

Introduction

Podman^1 is a container management software similar to Docker that can run OCI containers as regular users (not root) by using container management libraries such as crun or runc, and cgroups v1 or v2. It can be used as a drop-in replacement for Docker and supports docker-compose using podman-compose.

Unfortunately for some distributions after installing podman the operating system defaults to cgroups v1 and runc, not cgroups v2 and crun. As was the case on Rocky Linux for me.

Switching to crun

First we can switch to crun instead of runc by installing crun with our package manager. It was already installed for me, but on Fedora you would use sudo dnf install crun

Then you can edit the file /usr/share/containers/containers.conf and change the line runtime = "runc" to runtime = "crun". Now you can verify that you’re using crun with podman info | grep crun.

name: crun
package: crun-0.20.1-1.module+el8.4.0+643+525e162a.x86_64
path: /usr/bin/crun
  crun version 0.20.1

Enabling cgroups v2

Now the harder part was enabling cgroups v2. Luckily I found a comment on a GitHub issue outlining the steps you need to complete to get cgroups v2 to work.

First we can enable it in the kernel with

sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=1"

Then we can enable linger. This will also allow our containers to remain running after logging out.

sudo loginctl enable-linger codebam

Then the last step which made everything work for me is to set the pid_limit=0. For me it was in /usr/share/containers/containers.conf instead of /etc/containers/.

Verification

Now you can reboot. podman info | grep cgroup should say

cgroupControllers: []
cgroupManager: systemd
cgroupVersion: v2

Now we’re using cgroups v2 and crun.