diff --git a/docs/hosting-runners-rootless.md b/docs/hosting-runners-rootless.md new file mode 100644 index 0000000..d6d2340 --- /dev/null +++ b/docs/hosting-runners-rootless.md @@ -0,0 +1,119 @@ +# 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. 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 +``` + +### 3. Install podman (rootless) + +```bash +# As root +apt install -y podman podman-docker + +# 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" +``` + +#### 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 + +```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 " +# aka "Forgejo Releases " + +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. :) + +czzHPHIWdsjroPohucX6WeLRo5V6Y9Y1L7CHlna6 + +```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="" +RUNNER_TOKEN="" +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__. diff --git a/docs/hosting-runners.md b/docs/hosting-runners.md index 228d843..b1c7a5b 100644 --- a/docs/hosting-runners.md +++ b/docs/hosting-runners.md @@ -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.