diff options
Diffstat (limited to 'examples')
| -rw-r--r-- | examples/README.md | 10 | ||||
| -rw-r--r-- | examples/docker-compose/README.md | 113 | ||||
| -rw-r--r-- | examples/docker-compose/compose-demo-workflow.yml | 35 | ||||
| -rw-r--r-- | examples/docker-compose/compose-forgejo-and-runner.yml | 93 | ||||
| -rw-r--r-- | examples/docker/README.md | 12 | ||||
| -rw-r--r-- | examples/kubernetes/README.md | 7 | ||||
| -rw-r--r-- | examples/kubernetes/dind-docker.yaml | 87 |
7 files changed, 357 insertions, 0 deletions
diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..f9dd774 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,10 @@ +This directory contains a collection of usage and deployment examples. + +Workflow examples can be found [in the documentation](https://forgejo.org/docs/next/user/actions/) +and in the [sources of the setup-forgejo](https://code.forgejo.org/actions/setup-forgejo/src/branch/main/testdata) action. + +| Section | Description | +|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`docker`](docker) | using the host docker server by mounting the socket | +| [`docker-compose`](docker-compose) | all in one docker-compose with the Forgejo server, the runner and docker in docker | +| [`kubernetes`](kubernetes) | a sample deployment for the Forgejo runner | diff --git a/examples/docker-compose/README.md b/examples/docker-compose/README.md new file mode 100644 index 0000000..a3e6e9b --- /dev/null +++ b/examples/docker-compose/README.md @@ -0,0 +1,113 @@ +## Docker compose with docker-in-docker + +The `compose-forgejo-and-runner.yml` compose file runs a Forgejo +instance and registers a `Forgejo runner`. A docker server is also +launched within a container (using +[dind](https://hub.docker.com/_/docker/tags?name=dind)) and will be +used by the `Forgejo runner` to execute the workflows. + +### Quick start + +```sh +rm -fr /srv/runner-data /srv/forgejo-data +secret=$(openssl rand -hex 20) +sed -i -e "s/{SHARED_SECRET}/$secret/" compose-forgejo-and-runner.yml +docker compose -f compose-forgejo-and-runner.yml up -d +``` + +Visit http://0.0.0.0:8080/admin/actions/runners with login `root` and password `{ROOT_PASSWORD}` and see the runner is registered with the label `docker`. + +> NOTE: the `Your ROOT_URL in app.ini is "http://localhost:3000/", it's unlikely matching the site you are visiting.` message is a warning that can be ignored in the context of this example. + +```sh +docker compose -f compose-forgejo-and-runner.yml -f compose-demo-workflow.yml up demo-workflow +``` + +Visit http://0.0.0.0:8080/root/test/actions/runs/1 and see that the job ran. + + +### Running + +Create a shared secret with: + +```sh +openssl rand -hex 20 +``` + +Replace all occurences of {SHARED_SECRET} in +[compose-forgejo-and-runner.yml](compose-forgejo-and-runner.yml). + +> **NOTE:** a token obtained from the Forgejo web interface cannot be used as a shared secret. + +Replace {ROOT_PASSWORD} with a secure password in +[compose-forgejo-and-runner.yml](compose-forgejo-and-runner.yml). + +```sh +docker compose -f compose-forgejo-and-runner.yml up +Creating docker-compose_docker-in-docker_1 ... done +Creating docker-compose_forgejo_1 ... done +Creating docker-compose_runner-register_1 ... done +... +docker-in-docker_1 | time="2023-08-24T10:22:15.023338461Z" level=warning msg="WARNING: API is accessible on http://0.0.0.0:2376 +... +forgejo_1 | 2023/08/24 10:22:14 ...s/graceful/server.go:75:func1() [D] Starting server on tcp:0.0.0.0:3000 (PID: 19) +... +runner-daemon_1 | time="2023-08-24T10:22:16Z" level=info msg="Starting runner daemon" +``` + +### Manual testing + +To login the Forgejo instance: + +* URL: http://0.0.0.0:8080 +* user: `root` +* password: `{ROOT_PASSWORD}` + +`Forgejo Actions` is enabled by default when creating a repository. + +## Tests workflow + +The `compose-demo-workflow.yml` compose file runs two demo workflows: +* one to verify the `Forgejo runner` can pick up a task from the Forgejo instance +and run it to completion. +* one to verify docker can be run inside the `Forgejo runner` container. + +A new repository is created in root/test with the following workflows: + +#### `.forgejo/workflows/demo.yml`: + +```yaml +on: [push] +jobs: + test: + runs-on: docker + steps: + - run: echo All Good +``` + +#### `.forgejo/workflows/demo_docker.yml` + +```yaml +on: [push] +jobs: + test_docker: + runs-on: ubuntu-22.04 + steps: + - run: docker info +``` + +A wait loop expects the status of the check associated with the +commit in Forgejo to show "success" to assert the workflow was run. + +### Running + +```sh +$ docker-compose -f compose-forgejo-and-runner.yml -f compose-demo-workflow.yml up demo-workflow +... +demo-workflow_1 | To http://forgejo:3000/root/test +demo-workflow_1 | + 5ce134e...261cc79 main -> main (forced update) +demo-workflow_1 | branch 'main' set up to track 'http://root:admin1234@forgejo:3000/root/test/main'. +... +demo-workflow_1 | running +... +``` diff --git a/examples/docker-compose/compose-demo-workflow.yml b/examples/docker-compose/compose-demo-workflow.yml new file mode 100644 index 0000000..90e7d52 --- /dev/null +++ b/examples/docker-compose/compose-demo-workflow.yml @@ -0,0 +1,35 @@ +# Copyright 2024 The Forgejo Authors. +# SPDX-License-Identifier: MIT + +services: + + demo-workflow: + image: code.forgejo.org/oci/alpine:3.19 + links: + - forgejo + command: >- + sh -ec ' + apk add --quiet git curl jq ; + mkdir -p /srv/demo ; + cd /srv/demo ; + git init --initial-branch=main ; + mkdir -p .forgejo/workflows ; + echo "{ on: [push], jobs: { test: { runs-on: docker, steps: [ {uses: actions/checkout@v4}, { run: echo All Good } ] } } }" > .forgejo/workflows/demo.yml ; + echo "{ on: [push], jobs: { test_docker: { runs-on: ubuntu-22.04, steps: [ { run: docker info } ] } } }" > .forgejo/workflows/demo_docker.yml ; + git add . ; + git config user.email root@example.com ; + git config user.name username ; + git commit -m demo ; + while : ; do + git push --set-upstream --force http://root:{ROOT_PASSWORD}@forgejo:3000/root/test main && break ; + sleep 5 ; + done ; + sha=`git rev-parse HEAD` ; + for delay in 1 1 1 1 2 5 5 10 10 10 15 30 30 30 30 30 30 30 ; do + curl -sS -f http://forgejo:3000/api/v1/repos/root/test/commits/$$sha/status | jq --raw-output .state | tee status ; + if grep success status ; then echo DEMO WORKFLOW SUCCESS && break ; fi ; + if grep failure status ; then echo DEMO WORKFLOW FAILURE && break ; fi ; + sleep $$delay ; + done ; + grep success status || echo DEMO WORKFLOW FAILURE + ' diff --git a/examples/docker-compose/compose-forgejo-and-runner.yml b/examples/docker-compose/compose-forgejo-and-runner.yml new file mode 100644 index 0000000..4794985 --- /dev/null +++ b/examples/docker-compose/compose-forgejo-and-runner.yml @@ -0,0 +1,93 @@ +# Copyright 2024 The Forgejo Authors. +# SPDX-License-Identifier: MIT + +# +# Create a secret with: +# +# openssl rand -hex 20 +# +# Replace all occurences of {SHARED_SECRET} below with the output. +# +# NOTE: a token obtained from the Forgejo web interface cannot be used +# as a shared secret. +# +# Replace {ROOT_PASSWORD} with a secure password +# + +volumes: + docker_certs: + +services: + + docker-in-docker: + image: code.forgejo.org/oci/docker:dind + hostname: docker # Must set hostname as TLS certificates are only valid for docker or localhost + privileged: true + environment: + DOCKER_TLS_CERTDIR: /certs + DOCKER_HOST: docker-in-docker + volumes: + - docker_certs:/certs + + forgejo: + image: codeberg.org/forgejo/forgejo:1.21 + command: >- + bash -c ' + /bin/s6-svscan /etc/s6 & + sleep 10 ; + su -c "forgejo forgejo-cli actions register --secret {SHARED_SECRET}" git ; + su -c "forgejo admin user create --admin --username root --password {ROOT_PASSWORD} --email root@example.com" git ; + sleep infinity + ' + environment: + FORGEJO__security__INSTALL_LOCK: "true" + FORGEJO__log__LEVEL: "debug" + FORGEJO__repository__ENABLE_PUSH_CREATE_USER: "true" + FORGEJO__repository__DEFAULT_PUSH_CREATE_PRIVATE: "false" + FORGEJO__repository__DEFAULT_REPO_UNITS: "repo.code,repo.actions" + volumes: + - /srv/forgejo-data:/data + ports: + - 8080:3000 + + runner-register: + image: code.forgejo.org/forgejo/runner:3.4.1 + links: + - docker-in-docker + - forgejo + environment: + DOCKER_HOST: tcp://docker-in-docker:2376 + volumes: + - /srv/runner-data:/data + user: 0:0 + command: >- + bash -ec ' + while : ; do + forgejo-runner create-runner-file --connect --instance http://forgejo:3000 --name runner --secret {SHARED_SECRET} && break ; + sleep 1 ; + done ; + sed -i -e "s|\"labels\": null|\"labels\": [\"docker:docker://code.forgejo.org/oci/node:20-bookworm\", \"ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04\"]|" .runner ; + forgejo-runner generate-config > config.yml ; + sed -i -e "s|network: .*|network: host|" config.yml ; + sed -i -e "s|^ envs:$$| envs:\n DOCKER_HOST: tcp://docker:2376\n DOCKER_TLS_VERIFY: 1\n DOCKER_CERT_PATH: /certs/client|" config.yml ; + sed -i -e "s|^ options:| options: -v /certs/client:/certs/client|" config.yml ; + sed -i -e "s| valid_volumes: \[\]$$| valid_volumes:\n - /certs/client|" config.yml ; + chown -R 1000:1000 /data + ' + + runner-daemon: + image: code.forgejo.org/forgejo/runner:3.4.1 + links: + - docker-in-docker + - forgejo + environment: + DOCKER_HOST: tcp://docker:2376 + DOCKER_CERT_PATH: /certs/client + DOCKER_TLS_VERIFY: "1" + volumes: + - /srv/runner-data:/data + - docker_certs:/certs + command: >- + bash -c ' + while : ; do test -w .runner && forgejo-runner --config config.yml daemon ; sleep 1 ; done + ' diff --git a/examples/docker/README.md b/examples/docker/README.md new file mode 100644 index 0000000..628c99c --- /dev/null +++ b/examples/docker/README.md @@ -0,0 +1,12 @@ +The following assumes: + +* a docker server runs on the host +* the docker group of the host is GID 133 +* a `.runner` file exists in /tmp/data +* a `runner-config.yml` file exists in /tmp/data + +```sh +docker run -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/data:/data --user 1000:133 --rm code.forgejo.org/forgejo/runner:3.0.0 forgejo-runner --config runner-config.yaml daemon +``` + +The workflows will run using the host docker srever diff --git a/examples/kubernetes/README.md b/examples/kubernetes/README.md new file mode 100644 index 0000000..d00cf1a --- /dev/null +++ b/examples/kubernetes/README.md @@ -0,0 +1,7 @@ +## Kubernetes Docker in Docker Deployment + +Registers Kubernetes pod runners using [offline registration](https://forgejo.org/docs/v1.21/admin/actions/#offline-registration), allowing the scaling of runners as needed. + +NOTE: Docker in Docker (dind) requires elevated privileges on Kubernetes. The current way to achieve this is to set the pod `SecurityContext` to `privileged`. Keep in mind that this is a potential security issue that has the potential for a malicious application to break out of the container context. + +[`dind-docker.yaml`](dind-docker.yaml) creates a deployment and secret for Kubernetes to act as a runner. The Docker credentials are re-generated each time the pod connects and does not need to be persisted. diff --git a/examples/kubernetes/dind-docker.yaml b/examples/kubernetes/dind-docker.yaml new file mode 100644 index 0000000..534432d --- /dev/null +++ b/examples/kubernetes/dind-docker.yaml @@ -0,0 +1,87 @@ +# Secret data. +# You will need to retrive this from the web UI, and your Forgejo instance must be running v1.21+ +# Alternatively, create this with +# kubectl create secret generic runner-secret --from-literal=token=your_offline_token_here +apiVersion: v1 +stringData: + token: your_offline_secret_here +kind: Secret +metadata: + name: runner-secret +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: forgejo-runner + name: forgejo-runner +spec: + # Two replicas means that if one is busy, the other can pick up jobs. + replicas: 2 + selector: + matchLabels: + app: forgejo-runner + strategy: {} + template: + metadata: + creationTimestamp: null + labels: + app: forgejo-runner + spec: + restartPolicy: Always + volumes: + - name: docker-certs + emptyDir: {} + - name: runner-data + emptyDir: {} + # Initialise our configuration file using offline registration + # https://forgejo.org/docs/v1.21/admin/actions/#offline-registration + initContainers: + - name: runner-register + image: code.forgejo.org/forgejo/runner:3.2.0 + command: ["forgejo-runner", "register", "--no-interactive", "--token", $(RUNNER_SECRET), "--name", $(RUNNER_NAME), "--instance", $(FORGEJO_INSTANCE_URL)] + env: + - name: RUNNER_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + - name: RUNNER_SECRET + valueFrom: + secretKeyRef: + name: runner-secret + key: token + - name: FORGEJO_INSTANCE_URL + value: http://forgejo-http.forgejo.svc.cluster.local:3000 + resources: + limits: + cpu: "0.50" + memory: "64Mi" + volumeMounts: + - name: runner-data + mountPath: /data + containers: + - name: runner + image: code.forgejo.org/forgejo/runner:3.0.0 + command: ["sh", "-c", "while ! nc -z localhost 2376 </dev/null; do echo 'waiting for docker daemon...'; sleep 5; done; forgejo-runner daemon"] + env: + - name: DOCKER_HOST + value: tcp://localhost:2376 + - name: DOCKER_CERT_PATH + value: /certs/client + - name: DOCKER_TLS_VERIFY + value: "1" + volumeMounts: + - name: docker-certs + mountPath: /certs + - name: runner-data + mountPath: /data + - name: daemon + image: docker:23.0.6-dind + env: + - name: DOCKER_TLS_CERTDIR + value: /certs + securityContext: + privileged: true + volumeMounts: + - name: docker-certs + mountPath: /certs |