provide details on the Docker & LXC requirements

admin/actions.md

@@ -4,35 +4,59 @@ title: 'Forgejo Actions'
 license: 'CC-BY-SA-4.0'
 ---
 
-`Forgejo Actions` provides continuous integration driven from the files in the `.forgejo/workflows` directory of a repository. It is still experimental and disabled by default and can be activated by adding the following to `app.ini`:
+`Forgejo Actions` provides continuous integration driven from the files in the `.forgejo/workflows` directory of a repository. It is still experimental and disabled by default. It can be activated by adding the following to `app.ini`:
 
 ```yaml
 [actions]
 ENABLED = true
 ```
 
-Forgejo does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so.
+`Forgejo` itself does not run the jobs, it relies on the [Forgejo runner](https://code.forgejo.org/forgejo/runner) to do so.
 
 # Forgejo runner
 
 ## Installation
 
-Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) into `/usr/local/bin/forgejo-runner` and change its permissions with `chmod +x /usr/local/bin/forgejo-runner`.
+Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) and verify their signature:
-
-The binaries are signed and should be verified to match with the following :
 
 ```shell
-$ wget https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64
+$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64
-$ wget https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64.asc
+$ chmod +x forgejo-runner
+$ wget -O forgejo-runner.asc https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64.asc
 $ gpg --keyserver keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
-$ gpg --verify forgejo-runner-amd64.asc forgejo-runner-amd64
+$ gpg --verify forgejo-runner.asc forgejo-runner
 Good signature from "Forgejo <contact@forgejo.org>"
                 aka "Forgejo Releases <release@forgejo.org>"
 ```
 
+### Docker
+
+For jobs to run in containers, the `Forgejo runner` needs access to [Docker](https://docs.docker.com/engine/install/).
+
+### LXC
+
+For jobs to run in LXC containers, the `Forgejo runner` needs passwordless sudo access on a Debian GNU/Linux bookworm system where [LXC](https://linuxcontainers.org/lxc/) is installed. The [LXC helpers](https://code.forgejo.org/forgejo/lxc-helpers/) can be used as follows to create a suitable container:
+
+```shell
+$ git clone https://code.forgejo.org/forgejo/lxc-helpers
+$ ./lxc-helpers/lxc-helpers.sh lxc_container_create myrunner
+$ ./lxc-helpers/lxc-helpers.sh lxc_container_start myrunner
+```
+
+The `Forgejo runner` can then be installed and run within the `myrunner` container.
+
+```shell
+$ ./lxc-helpers/lxc-helpers.sh lxc_container_run bash
+# apt-get install docker.io wget gnupg2
+# wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.0.3/forgejo-runner-amd64
+...
+```
+
+**Warning:** LXC containers do not provide a level of security that makes them safe for potentially malicious users to run jobs. They provide an excellent isolation for jobs that may accidentally damage the system they run on.
+
 ## Registration
 
-The runner is driven by a Forgejo instance and must register itself. It will be given permission to read the repositories and send back information to Forgejo such as the logs or its status. A special kind of token is needed and can be obtained from the `Create new runner` button:
+The `Forgejo runner` needs to connect to a `Forgejo` instance and must register itself before doing so. It will be given permission to read the repositories and send back information to `Forgejo` such as the logs or its status. A special kind of token is needed and can be obtained from the `Create new runner` button:
 
 - in `/admin/runners` to gain access to all repositories.
 - in `/{owner}/{repository}/settings/actions/runners` to gain access to a single repository.
@@ -40,7 +64,7 @@ The runner is driven by a Forgejo instance and must register itself. It will be
 For instance, using a token obtained for a test repository from `next.forgejo.org`:
 
 ```shell
-forgejo-runner-amd64 register --no-interactive --token {TOKEN} --name runner --instance https://next.forgejo.org --labels ubuntu-latest:docker://node:16-buster,self-hosted
+forgejo-runner register --no-interactive --token {TOKEN} --name runner --instance https://next.forgejo.org --labels ubuntu-latest:docker://node:16-buster,self-hosted
 INFO Registering runner, arch=amd64, os=linux, version=2.0.3.
 WARN Runner in user-mode.
 DEBU Successfully pinged the Forgejo instance server
@@ -51,7 +75,7 @@ It will create a `.runner` file that looks like:
 
 ```json
 {
-  "WARNING": "This file is automatically generated. Do not edit it manually unless you know what you are doing.",
+  "WARNING": "This file is automatically generated. Do not edit.",
   "id": 6,
   "uuid": "fcd0095a-291c-420c-9de7-965e2ebaa3e8",
   "name": "runner",
@@ -63,10 +87,10 @@ It will create a `.runner` file that looks like:
 
 ## Running
 
-Once Forgejo runner is successfully registered, it can be run from the directory in which the `.runner` file is found with:
+Once the `Forgejo runner` is successfully registered, it can be run from the directory in which the `.runner` file is found with:
 
 ```shell
-$ forgejo-runner-amd64 daemon
+$ forgejo-runner daemon
 INFO[0000] Starting runner daemon
 ```
 
@@ -81,7 +105,7 @@ jobs:
       - run: echo All Good
 ```
 
-Will send a job request to the runner that will show logs such as:
+Will send a job request to the `Forgejo runner` that will display logs such as:
 
 ```shell
 ...
@@ -92,13 +116,13 @@ INFO[2023-05-28T18:54:53+02:00] task 29 repo is earl-warren/test https://code.fo
 [/test]   ✅  Success - Main echo All Good
 ```
 
-It will also show in the `Actions` tab of the repository.
+It will also show a similar output in the `Actions` tab of the repository.
 
-If no runner is available, Forgejo will wait for it and submit the job as soon as it connects.
+If no `Forgejo runner` is available, `Forgejo` will wait for one to connect and submit the job as soon as it is available.
 
 ## Job environment
 
-The jobs defined in the files found in `.forgejo/workflows` specify the environment they need with `runs-on`. Each runner declares, with the `--labels` option` which one they support so Forgejo knows to submit jobs accordingly. For instance if a job has:
+The jobs defined in the files found in `.forgejo/workflows` specify the environment they need to run with `runs-on`. Each `Forgejo runner` declares, with the `--labels` option, which one they support so `Forgejo` knows to submit jobs accordingly. For instance if a job has:
 
 ```yaml
 runs-on: ubuntu-latest
@@ -108,7 +132,7 @@ the job will be submitted to a runner that registered with `--labels ubuntu-late
 
 ### Docker
 
-If `runs-on` matches a label that starts with `docker://`, the rest of it is interpreted as a container image. The runner will execute all the steps, as root, within a container created from that image.
+If `runs-on` is matched to a label that contains `docker://`, the rest of it is interpreted as a container image. The runner will execute all the steps, as root, within a container created from that image.
 
 ### LXC