mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-04 17:19:52 +00:00
silverwind
be6aefc7e8
The runner pages had drifted from the runner. They claimed Podman is unsupported, a registration retry limit of 10, a `container.env` proxy override that has no effect, and they used the deprecated `generate-config` command, while the actual instructions were buried under implementation details. The develop and 5.x pages are rewritten from the current runner sources (`main` is `v5.2.0`). They are shorter and aimed at operators, with a new page covering what jobs get. The reference generator now documents the `config` command, and the quickstart pages in every language use the `gitea-runner` binary name. Reviewed-on: https://gitea.com/gitea/docs/pulls/600 Reviewed-by: Lunny Xiao <[email protected]> Co-authored-by: silverwind <[email protected]>
101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
---
|
|
sidebar_position: 2
|
|
---
|
|
|
|
# Install with Docker
|
|
|
|
Runner images are available on [Docker Hub](https://hub.docker.com/r/gitea/runner/tags) as `docker.io/gitea/runner`. On its first start, the container registers and starts the runner:
|
|
|
|
```bash
|
|
docker run -d --name gitea-runner --restart always --privileged \
|
|
-e GITEA_INSTANCE_URL=https://gitea.example.com \
|
|
-e GITEA_RUNNER_REGISTRATION_TOKEN=<token> \
|
|
-v ./data:/data \
|
|
-v runner-docker:/var/lib/docker \
|
|
docker.io/gitea/runner:nightly-dind
|
|
```
|
|
|
|
The `-dind` image runs its own Docker daemon for jobs. Jobs never get access to the host's Docker daemon socket, which grants the equivalent of root access on the host. The two volumes preserve registration and job images when you replace the container:
|
|
|
|
- `/data` holds the `.runner` registration file. Without it, a new container registers as another runner.
|
|
- `/var/lib/docker` holds the images pulled for jobs. Without it, a new container pulls them again.
|
|
|
|
## Image flavours
|
|
|
|
| Tag | Docker daemon for jobs |
|
|
| --- | --- |
|
|
| `nightly-dind` (recommended) | Bundled. Requires `--privileged`. |
|
|
| `nightly-dind-rootless` | Bundled. Runs as UID 1000. Requires `--privileged` and [rootless Docker](https://docs.docker.com/engine/security/rootless/) support on the host. Stores its images in `/home/rootless/.local/share/docker`. |
|
|
| `nightly` | None. Mount the host's Docker daemon socket with `-v /var/run/docker.sock:/var/run/docker.sock`, or set `DOCKER_HOST`. |
|
|
|
|
The `latest` and release version tags use the same suffixes, for example `latest-dind`. The `-dind` flavours are available for amd64 and arm64. The basic image also supports riscv64 and s390x. The images are designed for Docker, not Podman.
|
|
|
|
When the basic image uses the host's Docker daemon, jobs share that daemon. Use this setup only for trusted repositories.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Meaning |
|
|
| --- | --- |
|
|
| `GITEA_INSTANCE_URL` | Gitea instance to register with. |
|
|
| `GITEA_RUNNER_REGISTRATION_TOKEN` | Registration token, needed only until registration completes. |
|
|
| `GITEA_RUNNER_REGISTRATION_TOKEN_FILE` | File to read the registration token from, such as a Docker secret. |
|
|
| `GITEA_RUNNER_NAME` | Runner name. Defaults to the container's hostname. |
|
|
| `GITEA_RUNNER_LABELS` | Comma-separated [labels](../labels.md), applied on every start. |
|
|
| `GITEA_RUNNER_EPHEMERAL` | Any nonempty value registers an [ephemeral runner](../registration.md#ephemeral-runners). |
|
|
| `GITEA_RUNNER_ONCE` | Any nonempty value makes the runner exit after one job. |
|
|
| `GITEA_MAX_REG_ATTEMPTS` | Maximum number of registration attempts. Unlimited by default, with 5 seconds between attempts. |
|
|
| `CONFIG_FILE` | Path to a [configuration file](../configuration.md) inside the container. |
|
|
|
|
To use a configuration file, mount it and set `CONFIG_FILE` to its path:
|
|
|
|
```bash
|
|
docker run ... -v ./config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml docker.io/gitea/runner:nightly-dind
|
|
```
|
|
|
|
## Docker Compose
|
|
|
|
```yaml
|
|
services:
|
|
runner:
|
|
image: docker.io/gitea/runner:nightly-dind
|
|
restart: always
|
|
privileged: true
|
|
environment:
|
|
GITEA_INSTANCE_URL: https://gitea.example.com
|
|
GITEA_RUNNER_REGISTRATION_TOKEN: <token>
|
|
volumes:
|
|
- ./data:/data
|
|
- runner-docker:/var/lib/docker
|
|
|
|
volumes:
|
|
runner-docker:
|
|
```
|
|
|
|
The rootless flavour needs these additional settings:
|
|
|
|
```yaml
|
|
services:
|
|
runner:
|
|
image: docker.io/gitea/runner:nightly-dind-rootless
|
|
restart: always
|
|
privileged: true
|
|
security_opt:
|
|
- apparmor=rootlesskit
|
|
environment:
|
|
GITEA_INSTANCE_URL: https://gitea.example.com
|
|
GITEA_RUNNER_REGISTRATION_TOKEN: <token>
|
|
DOCKERD_ROOTLESS_ROOTLESSKIT_NET: slirp4netns
|
|
DOCKERD_ROOTLESS_ROOTLESSKIT_MTU: 65520
|
|
volumes:
|
|
- runner-data:/data
|
|
|
|
volumes:
|
|
runner-data:
|
|
```
|
|
|
|
- Set `security_opt` on AppArmor hosts such as Ubuntu and Debian. Docker's `docker-ce-rootless-extras` package provides the `rootlesskit` profile.
|
|
- Use `slirp4netns` for better job network throughput than the default.
|
|
- Make `/data` writable by UID 1000. Use a named volume or a bind-mounted host directory owned by that UID.
|
|
|
|
See the runner repository's [examples](https://gitea.com/gitea/runner/src/branch/main/examples) for more deployments.
|