From 1a61c50fc19b17a0677336911202e243e743b932 Mon Sep 17 00:00:00 2001 From: Alan Grainger Date: Wed, 18 Sep 2024 16:45:41 +0200 Subject: [PATCH] docs: add podman auto-start info and cleanup structure (#200) --- README.md | 73 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 56 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 3a239ce..c38d536 100644 --- a/README.md +++ b/README.md @@ -22,11 +22,13 @@ Please take a look at the included modifications, and help us improve uCore if t - [Manual Install/Rebase](#manual-installrebase) - [Tips and Tricks](#tips-and-tricks) - [CoreOS and ostree Docs](#coreos-and-ostree-docs) - - [Immutability and Podman](#immutability-and-podman) + - [Podman](#podman) + - [Immutability and Podman](#immutability-and-podman) + - [Docker/Moby and Podman](#dockermoby-and-podman) + - [Podman and FirewallD](#podman-and-firewalld) + - [Automatically start containers on boot](#automatically-start-containers-on-boot) - [Default Services](#default-services) - [SELinux Troubleshooting](#selinux-troubleshooting) - - [Docker/Moby and Podman](#dockermoby-and-podman) - - [Podman and FirewallD](#podman-and-firewalld) - [Distrobox](#distrobox) - [NAS - Storage](#nas---storage) - [NFS](#nfs) @@ -212,12 +214,62 @@ sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/IMAGE:TAG It's a good idea to become familar with the [Fedora CoreOS Documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/) as well as the [CoreOS rpm-ostree docs](https://coreos.github.io/rpm-ostree/). Note especially, this image is only possible due to [ostree native containers](https://coreos.github.io/rpm-ostree/container/). -### Immutability and Podman +### Podman + +#### Immutability and Podman A CoreOS root filesystem system is immutable at runtime, and it is not recommended to install packages like in a mutable "normal" distribution. Fedora CoreOS expects the user to run services using [podman](https://podman.io). `moby-engine`, the free Docker implementation, is also installed for those who desire docker instead of podman. +#### Docker/Moby and Podman + +> [!IMPORTANT] +> CoreOS [cautions against](https://docs.fedoraproject.org/en-US/fedora-coreos/faq/#_can_i_run_containers_via_docker_and_podman_at_the_same_time) running podman and docker containers at the same time. Thus, `docker.socket` is disabled by default to prevent accidental activation of the docker daemon, given podman is the default. +> +> Ony run both simultaneously if you understand the risk. + +#### Podman and FirewallD + +Podman and firewalld [can sometimes conflict](https://github.com/ublue-os/ucore/issues/90) such that a `firewall-cmd --reload` removes firewall rules generated by podman. + +As of [netavark v1.9.0](https://blog.podman.io/2023/11/new-netavark-firewalld-reload-service/) a service is provided to handle re-adding netavark (Podman) firewall rules after a firewalld reload occurs. If needed, enable like so: `systemctl enable netavark-firewalld-reload.service` + +#### Automatically start containers on boot + +By default, UCore does not automatically start `restart: always` containers on system boot, however this can be easily enabled: + +##### For containers running under the `core` user + +```bash +# Copy the system's podman-restart service to the user location +cp /lib/systemd/system/podman-restart.service /var/home/core/.config/systemd/user + +# Enable the user service +systemctl --user enable podman-restart.service + +# Check that it's running +systemctl --user list-unit-files | grep podman +``` + +When you next reboot the system, your `restart: always` containers will automatically start. + +You may also need to enable “linger” mode on your user session, to prevent containers exiting which you have started interactively. To do that, run: + +```bash +loginctl enable-linger $UID +``` + +You can find more information regarding this on the [Podman troubleshooting page](https://github.com/containers/podman/blob/main/troubleshooting.md#21-a-rootless-container-running-in-detached-mode-is-closed-at-logout). + +##### For containers running under the root user (rootful containers) + +You just need to enable the built-in service: + +```bash +sudo systemctl enable podman-restart.service +``` + ### Default Services To maintain this image's suitability as a minimal container host, most add-on services are not auto-enabled. @@ -256,19 +308,6 @@ Enforcing Fedora provides useful docs on [SELinux troubleshooting](https://docs.fedoraproject.org/en-US/quick-docs/selinux-troubleshooting/). -### Docker/Moby and Podman - -> [!IMPORTANT] -> CoreOS [cautions against](https://docs.fedoraproject.org/en-US/fedora-coreos/faq/#_can_i_run_containers_via_docker_and_podman_at_the_same_time) running podman and docker containers at the same time. Thus, `docker.socket` is disabled by default to prevent accidental activation of the docker daemon, given podman is the default. -> -> Ony run both simultaneously if you understand the risk. - -### Podman and FirewallD - -Podman and firewalld [can sometimes conflict](https://github.com/ublue-os/ucore/issues/90) such that a `firewall-cmd --reload` removes firewall rules generated by podman. - -As of [netavark v1.9.0](https://blog.podman.io/2023/11/new-netavark-firewalld-reload-service/) a service is provided to handle re-adding netavark (Podman) firewall rules after a firewalld reload occurs. If needed, enable like so: `systemctl enable netavark-firewalld-reload.service` - ### Distrobox Users may use [distrobox](https://github.com/89luca89/distrobox) to run images of mutable distributions where applications can be installed with traditional package managers. This may be useful for installing interactive utilities such has `htop`, `nmap`, etc. As stated above, however, *services* should run as containers.