nprasad2077/runner
1
0 Fork 0
mirror of https://gitea.com/gitea/runner.git synced 2026-11-07 07:40:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: recommend DinD for container jobs (#1258)

Browse Source 
Make Docker-in-Docker the recommended and first-shown setup. Mounting the host's Docker socket gives every job root-equivalent access to the host, while DinD gives jobs their own daemon. The default `latest` tag is unchanged.

Also shorten the image flavour docs to what users need to pick an image, and correct that `dind-rootless` needs `--privileged` too.

Closes https://gitea.com/gitea/runner/issues/1227

---------

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/runner/pulls/1258
Reviewed-by: silverwind <[email protected]>
Co-authored-by: bircni <[email protected]>
This commit is contained in:
bircnisilverwindsilverwind
 authored and silverwind committed 2026-09-30 18:27:11 +00:00
1 parent 4a8ee4ce57
commit 78610b01f6
3 files changed
+25 -47
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

examples/docker-compose/README.md
+6 -5
View File
@@ -1,5 +1,7 @@
### Running `gitea-runner` using `docker-compose`
This uses the recommended Docker-in-Docker image, see [image flavours](../../README.md#image-flavours).
```yml
...
gitea:
@@ -19,8 +21,9 @@
# - GITEA_RUNNER_REGISTRATION_TOKEN=<user-defined registration token>
runner:
image: gitea/runner
image: gitea/runner:latest-dind
restart: always
privileged: true
depends_on:
gitea:
# required so runner can attach to gitea, see "healthcheck"
@@ -28,7 +31,6 @@
restart: true
volumes:
- ./data/runner:/data
- /var/run/docker.sock:/var/run/docker.sock
environment:
- GITEA_INSTANCE_URL=<instance url>
# When using Docker Secrets, it's also possible to use
@@ -38,10 +40,9 @@
- GITEA_RUNNER_REGISTRATION_TOKEN=<registration token>
```
### Running `gitea-runner` using Docker-in-Docker (DIND)
### Running `gitea-runner` using rootless Docker-in-Docker
- `privileged` has to be set to `true` because in-container Docker daemon requires a lot of kernel capabilities and file system mounts like `procfs` and `sysfs`
- `security_opt` sets the `apparmor` profile to `rootlesskit` for hosts running AppArmor (e.g. Ubuntu, Debian), where the kernel might otherwise block user namespace changes that Docker daemon requires for startup. The `rootlesskit` profile is provided by the `docker-ce-rootless-extras` package and is present on hosts where Docker was installed via the official installer or distro packages
On AppArmor hosts such as Ubuntu and Debian, `security_opt` is needed for the daemon to start. Docker's `docker-ce-rootless-extras` package provides the `rootlesskit` profile.
```yml
...
examples/docker/README.md
+9 -3
View File
@@ -1,8 +1,14 @@
### Run `gitea-runner` in a Docker Container
The recommended Docker-in-Docker image runs its own Docker daemon for jobs, so they never get the host's Docker socket:
```sh
docker run -e GITEA_INSTANCE_URL=http://192.168.8.18:3000 -e GITEA_RUNNER_REGISTRATION_TOKEN=<runner_token> -v /var/run/docker.sock:/var/run/docker.sock -v $PWD/data:/data --name my_runner gitea/runner:nightly
docker run --privileged \
-e GITEA_INSTANCE_URL=http://192.168.8.18:3000 \
-e GITEA_RUNNER_REGISTRATION_TOKEN=<runner_token> \
-v "$PWD/data:/data" \
-v runner-docker:/var/lib/docker \
--name my_runner gitea/runner:nightly-dind
```
The `/data` directory inside the docker container contains the runner API keys after registration.
It must be persisted, otherwise the runner would try to register again, using the same, now defunct registration token.
The volumes keep the runner's registration and the job image cache. See [image flavours](../../README.md#image-flavours) for alternatives.