Installation of forgejo-runner via docker - which docs should one use? #1377

CSDUMMI commented 2025年08月11日 09:45:00 +02:00

I think there is an inconsistency between the docs and the example docker-compose files linked by them.

The docs describe a process with:

• data.forgejo.org/forgejo/runner:4.0.0 (current version is 9.0.3) as the runner image.
• docker:dind as the dind image.
• It advices to edit docker compose file after registering the runner.

The examples on the other hand use:

• code.forgejo.org/forgejo/runner:9.0.3 for the runner.
• code.forgejo.org/oci/docker:dind for the dind
• Also run a forgejo instance on the same machine (something the docs warn against).
• It has separate services runner-register and runner-daemon.

This is very confusing. Could the docs use an update?

I think there is an inconsistency between the docs and the example docker-compose files linked by them. The [docs](https://codeberg.org/forgejo/docs/src/branch/next/docs/admin/actions/runner-installation.md#oci-image-installation) describe a process with: - `data.forgejo.org/forgejo/runner:4.0.0` (current version is `9.0.3`) as the runner image. - `docker:dind` as the dind image. - It advices to edit docker compose file after registering the runner. The [examples](https://code.forgejo.org/forgejo/runner/src/branch/main/examples/docker-compose/compose-forgejo-and-runner.yml) on the other hand use: - `code.forgejo.org/forgejo/runner:9.0.3` for the runner. - `code.forgejo.org/oci/docker:dind` for the `dind` - Also run a forgejo instance on the same machine (something the docs warn against). - It has separate services `runner-register` and `runner-daemon`. This is very confusing. Could the docs use an update?

earl-warren commented 2025年08月11日 13:37:49 +02:00

The examples receive automated updates and run in the CI, which explains why they are more up to date. The doc needs manual attention.

Could you please review #1378?

The examples receive automated updates and run in the CI, which explains why they are more up to date. The doc needs manual attention. Could you please review https://codeberg.org/forgejo/docs/pulls/1378?

CSDUMMI commented 2025年08月11日 18:22:04 +02:00

Thanks for the quick PR.

Regarding the registration process, is editing the docker-compose file after registration really the best way to setup a docker-compose based runner?

Thanks for the quick PR. Regarding the registration process, is editing the docker-compose file after registration really the best way to setup a docker-compose based runner?

CSDUMMI commented 2025年08月11日 18:52:34 +02:00

I think a simpler docker-compose.yml file to use in the docs would be:

services:docker-in-docker:image:code.forgejo.org/oci/docker:dindhostname:dockerprivileged:trueenvironment:DOCKER_TLS_CERTDIR:/certsDOCKER_HOST:docker-in-dockervolumes:- ./certs:/certsrunner:image:code.forgejo.org/forgejo/runner:9.0.3environment:DOCKER_HOST:tcp://docker:2376DOCKER_CERT_PATH:/certs/clientDOCKER_TLS_VERIFY:"1"depends_on:docker-in-docker:condition:service_startedvolumes:- ./data:/data- ./certs:/certsuser:1001:1001command:forgejo-runner daemon

And to then use docker compose run -u 1001 --rm -it runner forgejo-runner register or create-runner-file to register the runner manually and offline, respectively?

After that the admin can run docker compose up -d and no modification to the docker-compose.yml file will be necessary.

I think a simpler `docker-compose.yml` file to use in the docs would be: ```yml services: docker-in-docker: image: code.forgejo.org/oci/docker:dind hostname: docker privileged: true environment: DOCKER_TLS_CERTDIR: /certs DOCKER_HOST: docker-in-docker volumes: - ./certs:/certs runner: image: code.forgejo.org/forgejo/runner:9.0.3 environment: DOCKER_HOST: tcp://docker:2376 DOCKER_CERT_PATH: /certs/client DOCKER_TLS_VERIFY: "1" depends_on: docker-in-docker: condition: service_started volumes: - ./data:/data - ./certs:/certs user: 1001:1001 command: forgejo-runner daemon ``` And to then use `docker compose run -u 1001 --rm -it runner forgejo-runner register` or `create-runner-file` to register the runner manually and offline, respectively? After that the admin can run `docker compose up -d` and no modification to the `docker-compose.yml` file will be necessary.

earl-warren commented 2025年08月11日 22:57:15 +02:00

The problem here is to go from something that works in theory (your docker compose seems fine) to something that is known to work. As a reviewer, how do you propose I verify what you propose actually works?

The problem here is to go from something that works in theory (your docker compose seems fine) to something that is known to work. As a reviewer, how do you propose I verify what you propose actually works?

CSDUMMI commented 2025年08月12日 09:04:34 +02:00

I can write up my approach as a PR to the docs and you can verify that following them will setup a runner and register it?

I can write up my approach as a PR to the docs and you can verify that following them will setup a runner and register it?

earl-warren commented 2025年08月12日 12:35:27 +02:00

@CSDUMMI wrote in #1377 (comment):

I can write up my approach as a PR to the docs and you can verify that following them will setup a runner and register it?

I can do that 👍

@CSDUMMI wrote in https://codeberg.org/forgejo/docs/issues/1377#issuecomment-6251590: > I can write up my approach as a PR to the docs and you can verify that following them will setup a runner and register it? I can do that 👍

CSDUMMI commented 2025年08月13日 19:42:23 +02:00

I've created a PR with what I think is a simplified setup guide using docker-compose.

Your review would be very welcome: #1385

I've created a PR with what I think is a simplified setup guide using docker-compose. Your review would be very welcome: https://codeberg.org/forgejo/docs/pulls/1385

benjaoming commented 2025年12月15日 13:59:42 +01:00

Sorry, I didn't see this issue before opening #1634 - but I think there are several issues going on:

• Running forgejo-runner register from a Docker Compose service... it seems everyone agrees this needs to happen 😄.
• Should the Docker Compose setup be elevated as the "default" setup? (I think so - it's the fastest and easiest instructions!). Open a new issue to discuss this? Yes/No?
• Additional changes to the dind service, adding the certs/ folder (proposed in #1385) - I'm not sure if this is necessary anymore, I haven't encountered issues.
• As offered, I can split out the firewall considerations from #1634 - but I think they're important.

Sorry, I didn't see this issue before opening https://codeberg.org/forgejo/docs/pulls/1634 - but I think there are several issues going on: * Running `forgejo-runner register` from a Docker Compose service... it seems everyone agrees this needs to happen 😄. * Should the Docker Compose setup be elevated as the "default" setup? (I think so - it's the fastest and easiest instructions!). **Open a new issue to discuss this? Yes/No?** * Additional changes to the dind service, adding the `certs/` folder (proposed in #1385) - I'm not sure if this is necessary anymore, I haven't encountered issues. * As offered, I can split out the firewall considerations from #1634 - but I think they're important.