podbox

What is this?

Make systemd better for Podman with Quadlet

This is a repository of ready-to-use quadlets. They allow you to run any container with podman using systemd unit files in your user session.

This means no root user is ever invoked from the host system. Everything runs under the same user permissions as yourself, from within your own $HOME.

Note

It is recommended to create another user specifically for running these containers, but it is not strictly required. Details for setting up a system from scratch are located in AlmaLinux.md.

Table of Contents

• Getting started
  • Dependencies
  • Quickstart
    • Hello, world
  • Running real apps
    • Example
• Coming soon

Getting started

Dependencies

• podman>=4.3.0
• systemd

You may need to add a large range of subuids and subgids, because podman will use them when users are generated inside the containers.

sudo usermod --add-subuids 200000-299999 --add-subgids 200000-299999 $USER

Quickstart

Hello, world

Create the following unit file at ~/.config/containers/systemd/helloworld.container.

[Unit]
Description=Hello, world

[Service]
Restart=on-failure
TimeoutStartSec=900

[Install]
WantedBy=default.target

[Container]
Image=quay.io/podman/hello
ContainerName=helloworld

Run the following commands to load and run the container.

systemctl --user daemon-reload
systemctl --user start helloworld
journalctl -e

You should see the following in your journal!

Dec 01 08:42:05 perseus systemd[1362]: Started hello world.
Dec 01 08:42:05 perseus helloworld[1143334]: !... Hello Podman World ...!
Dec 01 08:42:05 perseus helloworld[1143334]:
Dec 01 08:42:05 perseus helloworld[1143334]:          .--"--.
Dec 01 08:42:05 perseus helloworld[1143334]:        / -     - \
Dec 01 08:42:05 perseus helloworld[1143334]:       / (O)   (O) \
Dec 01 08:42:05 perseus helloworld[1143334]:    ~~~| -=(,Y,)=- |
Dec 01 08:42:05 perseus helloworld[1143334]:     .---. /`  \   |~~
Dec 01 08:42:05 perseus helloworld[1143334]:  ~/  o  o \~~~~.----. ~~
Dec 01 08:42:05 perseus helloworld[1143334]:   | =(X)= |~  / (O (O) \
Dec 01 08:42:05 perseus helloworld[1143334]:    ~~~~~~~  ~| =(Y_)=-  |
Dec 01 08:42:05 perseus helloworld[1143334]:   ~~~~    ~~~|   U      |~~
Dec 01 08:42:05 perseus helloworld[1143334]:
Dec 01 08:42:05 perseus helloworld[1143334]: Project:   https://github.com/containers/podman
Dec 01 08:42:05 perseus helloworld[1143334]: Website:   https://podman.io
Dec 01 08:42:05 perseus helloworld[1143334]: Desktop:   https://podman-desktop.io
Dec 01 08:42:05 perseus helloworld[1143334]: Documents: https://docs.podman.io
Dec 01 08:42:05 perseus helloworld[1143334]: YouTube:   https://youtube.com/@Podman
Dec 01 08:42:05 perseus helloworld[1143334]: X/Twitter: @Podman_io
Dec 01 08:42:05 perseus helloworld[1143334]: Mastodon:  @[email protected]

Running real apps

1. Copy the quadlets/$app/ you want to run to $XDG_CONFIG_HOME/containers/systemd/quadlets/
2. Edit the files to match your system
   • Set your Network=... for containers that need to share a network namespace
   • Set Volume=...:... to a path that exists on your system if you need to access it within that container
   • Modify environment variables with Environment=... or use an env file with EnvironmentFile=./path/to/foo.env
3. Load the updated container definition into systemd
4. Launch the container

Example

# Step 1
git clone --depth=1 https://github.com/redbeardymcgee/podbox
cp -a podbox/quadlets/thelounge "$XDG_CONFIG_HOME"/containers/systemd/
# Step 2
$EDITOR "$XDG_CONFIG_HOME"/containers/systemd/thelounge/*
# Step 3
systemctl --user daemon-reload
# Step 4
systemctl --user start thelounge

Navigate to http://localhost:9000 in your browser.

Warning

If the application is not found, confirm that the service is listening on port 9000 with ss -tunlp. You should see something similar to the following in your output:

Netid State  Recv-Q Send-Q Local Address:Port  Peer Address:PortProcess
tcp   LISTEN 0      4096       *:9000           *:*   users:(("rootlessport",pid=913878,fd=10))

Coming soon

I'm working on new quadlets every day. This is a list of all of the containers that I intend to add to this repository. It is still growing, and I welcome pull requests.

• Actual
• AdGuard
• Apprise
• ArgoCD
• Audiobookshelf
• Authelia
• Authentik
• betanin
• Bigcapital
• Bitwarden
• Blinko
• booktree
• Cabot
• Caddy # Socket activation requires newer caddy and podman
• Calibre
• Calibre-web
• ChartDB
• Checkmate
• Code::Stats
• dash.
• Dashy
• Dittofeed
• Duplicacy
• Duplicati
• EmulatorJS
• Filebrowser
• FiveFilters
• Foundry VTT
• FreshRSS
• Gaseous
• Glances
• glueforward
• gluetun
• Graphite
• Healthchecks
• hoarder
• Homarr
• Homepage
• IT-Tools
• Kavita
• Keycloak
• Kibitzr
• Komga
• LazyLibrarian
• librespeed
• Linkwarden
• Lounge
• Matrix
• Maxun
• Mealie
• Miniflux
• n8n
• Netbird
• netboot.xyz
• Netdata
• Note Mark
• Notesnook
• ntop
• OpenNMS
• PiHole
• Pocket ID
• Pod Arcade
• Postiz
• protonmail-bridge-docker
• ProtonMailBridgeDocker
• Prowlarr
• qbit_manage
• qBittorrent
• qbittorrent-port-forward-gluetun-server
• Radarr
• RomM
• Seafile
• Shiori
• SimpleX
• Snowflake
• solidtime
• Sonarr
• Stirling PDF
• Supervisord
• Tandoor
• traggo
• Ubooquity
• Umami
• UrBackup
• Vikunja
• Wazuh
• wger
• Zenoss
• Zitadel