forsaken-ashbirds/git.forsaken-ashbirds.net
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity Actions

Split docs to split rootfull & rootless hosting

Browse source
This commit is contained in:
Magnus Leßmann (@MarkL4YG) 2025-01-08 23:38:29 +01:00
parent 20d349e701
commit 08b9ee1f7d
Signed by: Mark.TwoFive
GPG key ID: 5B5EBCBE331F1E6F
3 changed files with 167 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/forgejo-runner.service
View file

@ -4,7 +4,7 @@ Documentation=https://forgejo.org/docs/latest/admin/actions/
After=podman-socket.service
[Service]
ExecStart=/home/forgejo-runner/.local/bin/forgejo-runner daemon
ExecStart=/home/forgejo-runner/.local/bin/forgejo-runner daemon -c /home/forgejo-runner/config.yml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/home/forgejo-runner
EnvironmentFile=/home/forgejo-runner/.runner-env

161
docs/hosting-runners-rootless.md Normal file
View file

@ -0,0 +1,161 @@
# Creating a new ForgeJo Runner Host
### IMPORTANT
### !! THIS SETUP DOES NOT WORK WITH IPv6-only HOSTS!!
Ubuntu 24.04 hosts running IPv6-only setup currently cannot use podman-rootless containers.
Somewhere in the networking stack, somebody messes up the routing causing all IPv6 networks to be unreachable from inside the container.
Podman maintainers/triagers seem to be keen on saying "this won't be an issue in Podman 5 with pasta anymore", however, that build is NOT available for Ubuntu 24.04 in its packet sources.
Building from source __might__ work, however GitHub seems to be unable to provide their service on IPv6 for some unknown *** reason.
Note for myself:
- Try to build and package podman 5 from another (ipv4-capable) machine and transfer the package over to the hetzner cloud.
- Try installing podman 5 from a third party API repository, if one exists.
## Machine Setup
### 1. Install Ubuntu (24.04)
For example on the Hetzner cloud.
### 2. Install podman (rootless) FROM SOURCE
(Hint: You can run all of the build stuff without root privileges, however ``apt install`` and ``make install`` will require sudo. 🙂)
```bash
# As root
# Ubuntu (>=23) thinks it is a good idea to disallow user namespaces for non-privileged users forcing us all to either use root or create apparmor profiles tailored for podman and its hundreds of tools.
echo "kernel.apparmor_restrict_unprivileged_userns = 0" > "/etc/sysctl.d/99-rootless-podman.conf"
echo "kernel.unprivileged_userns_clone = 1" >> "/etc/sysctl.d/99-rootless-podman.conf"
```
The podman binaries in the Ubuntu repositories for 24.04 are too outdated (4.X.X) for proper IPv6 support.
(According to the Podman devs, all of it is better with Pasta - which is the preferred rootless networking backend for Podman 5+)
__See [their docs](https://podman.io/docs/installation#building-from-source) on how to do that.__
(You can skip the 99-userns.conf command because we already did that above ⬆️)
> ⚠️ Please note the following ⚠️
> * After cloning the podman repository, checkout the latest release tag (the docs forget to mention that!)
> * Make sure to install ``libapparmor-dev libsystemd-dev`` before compiling so that the compatibility can be included in the installation.
> We recommend running make with ``BUILDTAGS="selinux seccomp apparmor exclude_graphdriver_devicemapper systemd"``
> * Run ``make vendor`` before running ``make install`` because for whatever reason it can be left out sometimes??
#### 2.1 Install crun from source
The crun version shipped by Ubuntu 24.04 is too old for Podman 5+. So we need to build it from source too...
```bash
git clone https://github.com/containers/crun
cd crun
git checkout "<latest-release-version>"
# <!-- Install dependencies for Ubuntu according to repository readme --!>
./autogen.sh
./configure
make
sudo make install # We need to change the prefix to overwrite what Ubuntu ships
```
#### 2.2 Containers configuration file
While the podman package installs the default configuration file below /usr/share/..., the make install command does not.
To make configuration easier for you later, please download the default configuration to ``/etc/containers/containers.conf``.
```bash
# As root
wget -O /etc/containers/containers.conf https://raw.githubusercontent.com/containers/common/refs/heads/main/pkg/config/containers.conf
sed -i 's/.*#runtime =.*/runtime = "\/usr\/local\/bin\/crun"/' /etc/containers/containers.conf # This updates the crun version used by podman - it really tries to use the outdated one otherwise.
# Note - This should yield "pasta", even on Ubuntu 24.04, if things worked so far.
podman info | grep rootlessNetworkCmd
# Note - This should show a crun version ABOVE 1.17
podman info | grep crun
```
### 3. Create a new user for the runner
Since we don't want to the new forgejo runner to be ``root`` on out machine, we create a new user for it:
```bash
# As root
useradd -s /bin/bash --create-home forgejo-runner
loginctl enable-linger forgejo-runner
```
#### Enable Podman docker-socket on user
```bash
# As root
apt install -y systemd-container
machinectl shell --uid forgejo-runner # <-- This is basically "sudo -Hi XXX" but makes sure the systemd container is switched too.
```
```bash
systemctl --user enable --now podman.socket podman
echo 'export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock' >> ~/.profile
source .profile # Refreshes shell vars, because .profile was modified.
```
### 4. Install the forgejo-runner
```bash
# As forgejo-runner
# Verify these URLs are still the version you want to install!!!
DOWNLOAD_URL="https://code.forgejo.org/forgejo/runner/releases/download/v5.0.4/forgejo-runner-5.0.4-linux-amd64"
SIG_URL="https://code.forgejo.org/forgejo/runner/releases/download/v5.0.4/forgejo-runner-5.0.4-linux-amd64.asc"
gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710 # Installs the signing key used by forgejo for their releases
wget -O forgejo-runner "$DOWNLOAD_URL"
wget -O forgejo-runner.asc "$SIG_URL"
gpg --verify forgejo-runner.asc forgejo-runner
# The output should now contain the following:
# Good signature from "Forgejo <contact@forgejo.org>"
# aka "Forgejo Releases <release@forgejo.org>"
mkdir -p ~/.local/bin
mv ./forgejo-runner ~/.local/bin/forgejo-runner
chmod 750 ~/.local/bin/forgejo-runner
```
### 5. Configure and register the forgejo-runner
__The official runner registration is__ [here](https://forgejo.org/docs/v8.0/admin/runner-installation/#standard-registration)
Or, if you're volunteering another runner for our instance, please contact us to receive the necessary registration information. :)
```bash
# As forgejo-runner (recreate shell to update PATH)
forgejo-runner generate-config > config.yml
# You should open the config.yml and enable IPv6 support! (Your cloud host might charge extra for IPv4 connectivity)
# We're about to enter secrets into the terminal, disable history:
set +o history
RUNNER_INST_URL="https://git.forsaken-ashbirds.net"
RUNNER_NAME="<PLEASE ENTER A UNIQUE NAME FOR YOUR RUNNER HERE!!!>"
RUNNER_TOKEN="<The token from the UI>"
RUNNER_LABELS="ubuntu-24.04,docker,podman,self-hosted" # Update these labels if you intend to change stuff!
# Re-enable history :)
set -o history
forgejo-runner register --instance "$RUNNER_INST_URL" --name "$RUNNER_NAME" --token "$RUNNER_TOKEN" --labels "$RUNNER_LABELS" --no-interactive
# You should see the following afterwards:
# INFO Runner registered successfully
```
#### Check the runner is working
```bash
# As forgejo-runner
echo "XDG_RUNTIME_DIR=/run/user/$(id -u)" > .runner-env
echo "DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock" >> .runner-env
mkdir -p ~/.config/systemd/user
# Download the file "docs/forgejo-runner.service" from this repository to "~/.config/systemd/user"
# Or create a new file there and paste the contents.
systemctl --user enable --now forgejo-runner
# View logs by using:
journalctl -xe --user-unit=forgejo-runner
# View status by using:
systemctl --user status forgejo-runner
```
__Go into Forgejo and check that your runner is shown as UP__.

41
docs/hosting-runners.md
View file

@ -6,39 +6,11 @@
For example on the Hetzner cloud.
### 2. Create a new user for the runner
### 2. Install Docker
Since we don't want to the new forgejo runner to be ``root`` on out machine, we create a new user for it:
```bash
# As root
useradd -s /bin/bash --create-home forgejo-runner
loginctl enable-linger forgejo-runner
```
See [Install using the API repository](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository)
### 3. Install podman (rootless)
```bash
# As root
apt install -y podman
# Expand the subuid/subgid namespaces for the user, the default one is too small for privileged rootless-containers
usermod --add-subuids 100000-200000 --add-subgids 100000-200000 forgejo-runner
```
#### Enable Podman docker-socket on user
```bash
# As root
apt install -y systemd-container
machinectl shell --uid forgejo-runner # <-- This is basically "sudo -Hi XXX" but makes sure the systemd container is switched too.
```
```bash
systemctl --user enable --now podman.socket podman
echo 'export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock' >> ~/.profile
```
### 4. Install the forgejo-runner
### 3. Install the forgejo-runner
```bash
# As forgejo-runner
@ -58,13 +30,13 @@ mv ./forgejo-runner ~/.local/bin/forgejo-runner
chmod 750 ~/.local/bin/forgejo-runner
```
### 5. Configure and register the forgejo-runner
### 4. Configure and register the forgejo-runner
__The official runner registration is__ [here](https://forgejo.org/docs/v8.0/admin/runner-installation/#standard-registration)
Or, if you're volunteering another runner for our instance, please contact us to receive the necessary registration information. :)
```bash
# As forgejo-runner
# As forgejo-runner (recreate shell to update PATH)
forgejo-runner generate-config > config.yml
# You should open the config.yml and enable IPv6 support! (Your cloud host might charge extra for IPv4 connectivity)
@ -86,9 +58,6 @@ forgejo-runner register --instance "$RUNNER_INST_URL" --name "$RUNNER_NAME" --to
```bash
# As forgejo-runner
echo "XDG_RUNTIME_DIR=/run/user/$(id -u)" > .runner-env
echo "DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock" >> .runner-env
mkdir -p ~/.config/systemd/user
# Download the file "docs/forgejo-runner.service" from this repository to "~/.config/systemd/user"
# Or create a new file there and paste the contents.