redbeardymcgee/podbox
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

improve getting started info and intro

Browse source
This commit is contained in:
redbeardymcgee 2024-12-01 15:35:05 -06:00
parent e949e3935b
commit 923356a8ef
1 changed files with 110 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

120
README.md
View file

@ -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/)