diff --git a/README.md b/README.md index 5afd5cc..e31f5b3 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,18 @@ ## What is this? -This repository represents my preferred method of managing containers. These -are `quadlets`, which is an interface between `systemd` and `podman`. +[Make `systemd` better for Podman with Quadlet](https://www.redhat.com/en/blog/quadlet-podman) -- [Make `systemd` better for Podman with Quadlet](https://www.redhat.com/en/blog/quadlet-podman) +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](./AlmaLinux.md). ## Getting started @@ -14,21 +22,113 @@ are `quadlets`, which is an interface between `systemd` and `podman`. - `podman>=4.3.0` - `systemd` -### Quickstart +You may need to add a large range of subuids and subgids, because `podman` will +use them when users are generated inside the containers. + +```bash +usermod --add-subuids 200000-299999 --add-subgids 200000-299999 $USER +``` + +### Quickstart + +#### Hello, world + +Create the following unit file at `~/.config/containers/systemd/helloworld.container`. + +```ini +[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. ```bash -git clone --depth=1 https://github.com/redbeardymcgee/podbox -cp -a "podbox/quadlets/$app" "$XDG_CONFIG_HOME/containers/systemd/" -# Edit the files in $XDG_CONFIG_HOME/containers/systemd/$app/ as needed -$EDITOR "$XDG_CONFIG_HOME/containers/systemd/$app/"* systemctl --user daemon-reload -systemctl --user start "$app" -# Jump to the end of the logs to see if the app started +systemctl --user start helloworld journalctl -e ``` +You should see the following in your journal! + +```bash +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: @Podman_io@fosstodon.org +``` + +### 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 + +```bash +# 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: +> +> ```bash +> Netid State Recv-Q Send-Q Local Address:Port Peer Address:PortProcess +> tcp LISTEN 0 4096 *:9000 *:* users:(("rootlessport",pid=913878,fd=10)) +> ``` + ## Upcoming containers +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 +your submissions on the [issue tracker](https://github.com/redbeardymcgee/podbox/issues). + - [x] [Actual](https://actualbudget.github.io/docs/) - [ ] [Apprise](https://github.com/caronc/apprise) - [x] [Audiobookshelf](https://www.audiobookshelf.org/)