From 1f260c12542e2cf81bc30dfcdb9e4389a9dca709 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Tue, 29 Oct 2024 09:11:48 +0100 Subject: [PATCH] admin: runner installation: recommend docker_host: "-" Defaulting to docker_host: "" will expose the underlying docker socket to all containers which is a security risk. The default must be the most secure setup. --- docs/admin/runner-installation.md | 45 +++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/docs/admin/runner-installation.md b/docs/admin/runner-installation.md index 9c904c5d..d15456d8 100644 --- a/docs/admin/runner-installation.md +++ b/docs/admin/runner-installation.md @@ -41,7 +41,7 @@ You should now be able to test the runner by running `forgejo-runner -v`: ``` $ forgejo-runner -v -forgejo-runner version v3.5.1 +forgejo-runner version v4.0.0 ``` ### Setting up the runner user @@ -94,7 +94,7 @@ The `Forgejo runner` relies on application containers (Docker, Podman, etc.) or ```shell $ lxc-helpers.sh lxc_container_run forgejo-runners -- sudo --user debian bash $ sudo apt-get install docker.io wget gnupg2 - $ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v3.4.1/forgejo-runner-amd64 + $ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v4.0.0/forgejo-runner-amd64 ... ``` @@ -133,6 +133,9 @@ displayed with `forgejo-runner generate-config`, stored in a $ forgejo-runner generate-config > config.yml # Example configuration file, it's safe to copy this as the default config file without any modification. +# You don't have to copy this file to your instance, +# just run `forgejo-runner generate-config > config.yaml` to generate a config file. + log: # The level of logging, can be trace, debug, info, warn, error, fatal level: info @@ -153,16 +156,24 @@ runner: # Please note that the Forgejo instance also has a timeout (3h by default) for the job. # So the job could be stopped by the Forgejo instance if it's timeout is shorter than this. timeout: 3h - # Whether skip verifying the TLS certificate of the Forgejo instance. + # The timeout for the runner to wait for running jobs to finish when + # shutting down because a TERM or INT signal has been received. Any + # running jobs that haven't finished after this timeout will be + # cancelled. + # If unset or zero the jobs will be cancelled immediately. + shutdown_timeout: 3h + # Whether skip verifying the TLS certificate of the instance. insecure: false # The timeout for fetching the job from the Forgejo instance. fetch_timeout: 5s # The interval for fetching the job from the Forgejo instance. fetch_interval: 2s + # The interval for reporting the job status and logs to the Forgejo instance. + report_interval: 1s # The labels of a runner are used to determine which jobs the runner can run, and how to run them. - # Like: ["macos-arm64:host", "ubuntu-latest:docker://node:16-bullseye", "ubuntu-22.04:docker://node:16-bullseye"] + # Like: ["macos-arm64:host", "ubuntu-latest:docker://node:20-bookworm", "ubuntu-22.04:docker://node:20-bookworm"] # If it's empty when registering, it will ask for inputting labels. - # If it's empty when execute `daemon`, will use labels in `.runner` file. + # If it's empty when executing the `daemon`, it will use labels in the `.runner` file. labels: [] cache: @@ -178,6 +189,10 @@ cache: # The port of the cache server. # 0 means to use a random available port. port: 0 + # The external cache server URL. Valid only when enable is true. + # If it's specified, it will be used to set the ACTIONS_CACHE_URL environment variable. The URL should generally end with "/". + # Otherwise it will be set to the the URL of the internal cache server. + external_server: "" container: # Specifies the network to which the container will connect. @@ -205,10 +220,12 @@ container: # - '**' valid_volumes: [] # overrides the docker client host with the specified one. - # If it's empty, act_runner will find an available docker host automatically. - # If it's "-", act_runner will find an available docker host automatically, but the docker host won't be mounted to the job containers and service containers. - # If it's not empty or "-", the specified docker host will be used. An error will be returned if it doesn't work. - docker_host: "" + # If "-", an available docker host will automatically be found. + # If empty, an available docker host will automatically be found and mounted in the job container (e.g. /var/run/docker.sock). + # Otherwise the specified docker host will be used and an error will be returned if it doesn't work. + docker_host: "-" + # Pull docker image(s) even if already present + force_pull: false host: # The parent directory of a job's working directory. @@ -259,14 +276,14 @@ The [OCI images](https://code.forgejo.org/forgejo/-/packages/container/runner/ve are built from the Dockerfile which is [found in the source directory](https://code.forgejo.org/forgejo/runner/src/branch/main/Dockerfile). It contains the `forgejo-runner` binary. ```shell -$ docker run --rm code.forgejo.org/forgejo/runner:3.4.1 forgejo-runner --version -forgejo-runner version v3.4.1 +$ docker run --rm code.forgejo.org/forgejo/runner:4.0.0 forgejo-runner --version +forgejo-runner version v4.0.0 ``` It does not run as root: ```shell -$ docker run --rm code.forgejo.org/forgejo/runner:3.4.1 id +$ docker run --rm code.forgejo.org/forgejo/runner:4.0.0 id uid=1000 gid=1000 groups=1000 ``` @@ -303,7 +320,7 @@ services: restart: 'unless-stopped' gitea: - image: 'code.forgejo.org/forgejo/runner:3.4.1' + image: 'code.forgejo.org/forgejo/runner:4.0.0' links: - docker-in-docker depends_on: @@ -356,7 +373,7 @@ To register the runner, excecute `forgejo-runner register` and fill in the promp ```shell $ forgejo-runner register -INFO Registering runner, arch=arm64, os=linux, version=v3.5.1. +INFO Registering runner, arch=arm64, os=linux, version=v4.0.0. WARN Runner in user-mode. INFO Enter the Forgejo instance URL (for example, https://next.forgejo.org/): https://code.forgejo.org/