Forgejo with Docker Compose
Forgejo is a self-hosted lightweight software forge. Easy to install and low maintenance, it just does the job. In the project's words: forgejo.org front page checked 2026-09-23
Replaces: GitHub. Forgejo's site calls it a "Self-hosted alternative to GitHub" that offers "a familiar environment to GitHub users". forgejo.org front page checked 2026-09-23
Runs on: amd64, arm64, arm/v7, arm/v6 from each image's registry manifest, checked 2026-09-30; a CPU counts only if every image has a build for it. Image by image
Add Forgejo to the builder to use your own domain and combine it with other apps in one file.
What Forgejo needs
Only figures Forgejo's own documentation publishes, each linked to the page it is on. Where the project gives no number, this page does not invent one.
| Resource | Minimum | Recommended |
|---|---|---|
| RAM | The project publishes no figure | |
| No figure. The project only says Forgejo "requires an order of magnitude less resources than other forges". Source: forgejo.org front page (Lightweight and performant) checked 2026-09-23 | ||
| CPU | The project publishes no figure | |
| Disk | The project publishes no figure | |
Which hardware Forgejo has images for
Read from each image's manifest list in its registry (anonymous, read-only) when this page was built. An app counts for a CPU only if every one of its images lists it.
With SQLite, the default
- x86-64 PC or NAS (
linux/amd64): every image has a build. - Raspberry Pi 4/5, 64-bit OS (
linux/arm64): every image has a build. - Raspberry Pi 3 or Zero 2 W, 32-bit OS (
linux/arm/v7): every image has a build;serveronly aslinux/arm/v6, which Docker pulls on a arm/v7 CPU when there is no arm/v7 build.
| Service | Image | Platforms in the manifest | Digest | Registry | Checked |
|---|---|---|---|---|---|
server | codeberg.org/forgejo/forgejo:16 | amd64, arm64, arm/v6 | sha256:cf5f5ae6acf2ababca0ee3d255705b83a47f35b25e07fc931d694d60664053fe | codeberg.org | 2026-09-25 |
With PostgreSQL
- x86-64 PC or NAS (
linux/amd64): every image has a build. - Raspberry Pi 4/5, 64-bit OS (
linux/arm64): every image has a build. - Raspberry Pi 3 or Zero 2 W, 32-bit OS (
linux/arm/v7): every image has a build;serveronly aslinux/arm/v6, which Docker pulls on a arm/v7 CPU when there is no arm/v7 build.
| Service | Image | Platforms in the manifest | Digest | Registry | Checked |
|---|---|---|---|---|---|
server | codeberg.org/forgejo/forgejo:16 | amd64, arm64, arm/v6 | sha256:cf5f5ae6acf2ababca0ee3d255705b83a47f35b25e07fc931d694d60664053fe | codeberg.org | 2026-09-25 |
db | postgres:14 | amd64, arm/v5, arm/v7, arm64, 386, ppc64le, riscv64, s390x | sha256:c2427de38f998489d36de7ca3553db2134872c400f2b08be4b824e5c50e4d619 | registry-1.docker.io | 2026-09-30 |
Git over SSH
The file below publishes only Caddy's ports, so Forgejo clones and pushes over HTTPS. Turn Git over SSH on and the compose file publishes Forgejo's SSH port beside Caddy, as the project's own example does (222:22), and sets the two settings Forgejo uses to print the SSH clone address. Every line is quoted from Forgejo's docs or its image's files.
Before the first push
- Firewall: Port 222/tcp must reach this server from wherever you push: open it in your VPS provider's firewall, or forward it on your router at home. A ufw rule does not close it, because Docker routes a published port before ufw sees it: “When you publish a container's ports using Docker, traffic to and from that container gets diverted before it goes through the ufw firewall settings.” Docker docs: Packet filtering and firewalls, Docker and ufw checked 2026-10-09
- Your key: Forgejo's own guide clones over HTTP and leaves SSH for later: “Although we use HTTP in this guide, it is a good idea to set up SSH-based authentication once you feel confident to do so.” Forgejo docs: Your First Repository checked 2026-10-09
- Make a key on your computer (Codeberg's docs, for its Forgejo): “ssh-keygen -t ed25519 -a 100” Codeberg docs: Adding an SSH key to your account (Codeberg runs Forgejo) checked 2026-10-09
ssh-keygen -t ed25519 -a 100
- Add the public half (the .pub file) in Forgejo: “Navigate to your user settings.” “Go to the section SSH / GPG Keys and click on Add key.” “Paste your key string into Content field.” Codeberg docs: Adding an SSH key to your account (Codeberg runs Forgejo) checked 2026-10-09
- Clone address: Forgejo then prints the SSH address on each repository page in the ssh:// form, with the user git, your SSH_DOMAIN and the port: “USE_COMPAT_SSH_URI: true: Always use ssh:// clone URL instead of scp-style URI.” Forgejo docs: Configuration Cheat Sheet (ROOT_URL, DISABLE_SSH) checked 2026-10-09 “ssh -F /dev/null git@<address> -p 222” Forgejo docs: Installation with Docker (docker-compose example, FORGEJO__section__KEY variables) checked 2026-10-09 “To clone your newly created repository, execute git clone with the URL that is shown in your repository:” Forgejo docs: Your First Repository checked 2026-10-09
ssh://git@git.example.org:222/<user>/<repo>.git - Test it: Forgejo's docs test it with this command, where <address> is your server: “Once SSH keys have been verified on Forgejo, to confirm functionality, run: ssh -F /dev/null git@<address> -p 222” Forgejo docs: Installation with Docker (docker-compose example, FORGEJO__section__KEY variables) checked 2026-10-09
ssh -F /dev/null git@<address> -p 222 - Not built here: sharing the server's own port 22 and its sshd with Forgejo (the "SSH passthrough" setups). Forgejo's docs cover the host's OpenSSH only for a Forgejo that runs on the host itself: “This section only applies if you’ve enabled SSH (enabled by default), and are using sshd provided by OpenSSH on the host.” Forgejo docs: Recommended Settings and Tips (OpenSSH recommendations) checked 2026-10-09
docker-compose.yml
Forgejo uses SQLite when no database is configured; the same Docker page shows PostgreSQL as a db service added to the file, and Forgejo supports PostgreSQL 14 and later. Choose before the first start: the installation page writes the database into app.ini, and neither page covers moving an existing instance from one database to the other. Source: Forgejo docs: Installation with Docker (PostgreSQL database section) checked 2026-09-30; Forgejo docs: Database Preparation (PostgreSQL >= 14) checked 2026-09-30
With SQLite, the default
This is exactly what the builder writes for Forgejo alone on example.org: the official definition with its published ports removed and Caddy added in front.
# docker-compose.yml built at dankhost.com for: Forgejo # Each app block is its official compose definition. Only the names were prefixed with # the app slug (services, containers, volumes, bind folders, .env variables) so any set of # apps can share one file; other differences are listed under "Changed:" in each block. # Only Caddy publishes ports. Secrets live in .env next to this file. services: # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ---- # Source: https://caddyserver.com/docs/running (checked 2026-09-23) # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23) # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly. caddy: image: "caddy:2" container_name: "caddy" restart: "unless-stopped" ports: - "80:80" - "443:443" - "443:443/udp" volumes: - "./caddy:/etc/caddy" - "caddy-data:/data" - "caddy-config:/config" networks: proxy: ipv4_address: "172.30.0.2" # ---- Forgejo (git.example.org) ---- # Source: https://forgejo.org/docs/latest/admin/installation/docker/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/setup/reverse-proxy/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/config-cheat-sheet/ (checked 2026-09-23) # Changed: Removed the documented '3000:3000' port; Caddy reaches forgejo-server:3000 on the proxy network. # Removed the documented '222:22' SSH port, because in this file only Caddy publishes ports. Git works over HTTPS only, and FORGEJO__server__DISABLE_SSH is set to true (the cheat sheet's 'Disable SSH feature when it's not available') so Forgejo stops offering SSH clone addresses that would not work. # Added FORGEJO__server__ROOT_URL, set to https://git.example.org/, using the documented FORGEJO__[SECTION]__[KEY] variable form; the cheat sheet says to override ROOT_URL when internal and external URLs differ, as they do in Docker. # The documented container_name 'forgejo' and network 'forgejo' are replaced by the builder's names: the service runs as forgejo-server on the proxy network. # Uses the documented default SQLite database. The docs' PostgreSQL variant is on dankhost.com/app/forgejo/ (the SQLite / PostgreSQL switch above the compose file); their MySQL variant is not offered. forgejo-server: image: "codeberg.org/forgejo/forgejo:16" container_name: "forgejo-server" environment: USER_UID: "1000" USER_GID: "1000" FORGEJO__server__ROOT_URL: "https://git.example.org/" FORGEJO__server__DISABLE_SSH: "true" restart: "always" volumes: - "./forgejo/forgejo:/data" - "/etc/localtime:/etc/localtime:ro" networks: proxy: {} networks: # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact. # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's # ipv4_address and in every trusted-proxy value to a free 172.x.0 range. proxy: ipam: config: - subnet: "172.30.0.0/24" ip_range: "172.30.0.128/25" gateway: "172.30.0.1" volumes: caddy-data: caddy-config:
With PostgreSQL
This is what the builder's code writes for Forgejo alone on example.org from the project's PostgreSQL setup (the builder on the front page still writes the SQLite version, so copy this one from here): the official definition with its published ports removed and Caddy added in front. Every ${VARIABLE} is defined in the .env below.
# docker-compose.yml built at dankhost.com for: Forgejo # Each app block is its official compose definition. Only the names were prefixed with # the app slug (services, containers, volumes, bind folders, .env variables) so any set of # apps can share one file; other differences are listed under "Changed:" in each block. # Only Caddy publishes ports. Secrets live in .env next to this file. services: # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ---- # Source: https://caddyserver.com/docs/running (checked 2026-09-23) # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23) # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly. caddy: image: "caddy:2" container_name: "caddy" restart: "unless-stopped" ports: - "80:80" - "443:443" - "443:443/udp" volumes: - "./caddy:/etc/caddy" - "caddy-data:/data" - "caddy-config:/config" networks: proxy: ipv4_address: "172.30.0.2" # ---- Forgejo (git.example.org) ---- # Source: https://forgejo.org/docs/latest/admin/installation/docker/ (checked 2026-09-30) # Source: https://forgejo.org/docs/latest/admin/setup/reverse-proxy/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/config-cheat-sheet/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/installation/database-preparation/ (checked 2026-09-30) # Source: https://hub.docker.com/_/postgres (checked 2026-09-30) # Source: https://www.postgresql.org/support/versioning/ (checked 2026-09-30) # Changed: Removed the documented '3000:3000' port; Caddy reaches forgejo-server:3000 on the proxy network. # Removed the documented '222:22' SSH port, because in this file only Caddy publishes ports. Git works over HTTPS only, and FORGEJO__server__DISABLE_SSH is set to true (the cheat sheet's 'Disable SSH feature when it's not available') so Forgejo stops offering SSH clone addresses that would not work. # Added FORGEJO__server__ROOT_URL, set to https://git.example.org/, using the documented FORGEJO__[SECTION]__[KEY] variable form; the cheat sheet says to override ROOT_URL when internal and external URLs differ, as they do in Docker. # The documented container_name 'forgejo' and network 'forgejo' are replaced by the builder's names: the service runs as forgejo-server on the proxy network. # Uses the PostgreSQL variant from the 'PostgreSQL database' section of the same docs page: the five FORGEJO__database__ variables on server, depends_on db, and a db service running postgres:14, the major version the docs pin. # The documented password 'forgejo' (in FORGEJO__database__PASSWD and POSTGRES_PASSWORD) is replaced by DB_PASSWORD, a random secret in .env; the documented user and database name, forgejo, are kept. # db sits only on the internal network it shares with server, publishes no port and is not on the proxy network; server reaches it as db:5432, the address the docs use. forgejo-server: image: "codeberg.org/forgejo/forgejo:16" container_name: "forgejo-server" environment: USER_UID: "1000" USER_GID: "1000" FORGEJO__database__DB_TYPE: "postgres" FORGEJO__database__HOST: "db:5432" FORGEJO__database__NAME: "forgejo" FORGEJO__database__USER: "forgejo" FORGEJO__database__PASSWD: "${FORGEJO_DB_PASSWORD}" FORGEJO__server__ROOT_URL: "https://git.example.org/" FORGEJO__server__DISABLE_SSH: "true" restart: "always" volumes: - "./forgejo/forgejo:/data" - "/etc/localtime:/etc/localtime:ro" depends_on: - "forgejo-db" networks: proxy: {} forgejo-backend: aliases: - "server" forgejo-db: image: "postgres:14" container_name: "forgejo-db" restart: "always" environment: POSTGRES_USER: "forgejo" POSTGRES_PASSWORD: "${FORGEJO_DB_PASSWORD}" POSTGRES_DB: "forgejo" volumes: - "./forgejo/postgres:/var/lib/postgresql/data" networks: forgejo-backend: aliases: - "db" networks: # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact. # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's # ipv4_address and in every trusted-proxy value to a free 172.x.0 range. proxy: ipam: config: - subnet: "172.30.0.0/24" ip_range: "172.30.0.128/25" gateway: "172.30.0.1" forgejo-backend: internal: true volumes: caddy-data: caddy-config:
With SQLite, the default
With Git over SSH on
The same file with Forgejo's SSH port published beside Caddy and labelled # PORT OUTSIDE THE PROXY, FORGEJO__server__DISABLE_SSH, FORGEJO__server__SSH_DOMAIN and FORGEJO__server__SSH_PORT set. Everything else is the off file, as the builder writes it for Forgejo alone on example.org.
# docker-compose.yml built at dankhost.com for: Forgejo # Each app block is its official compose definition. Only the names were prefixed with # the app slug (services, containers, volumes, bind folders, .env variables) so any set of # apps can share one file; other differences are listed under "Changed:" in each block. # Caddy publishes 80 and 443. The only other published ports, each labelled where # it is written: 222/tcp (Forgejo: Git over SSH). # Secrets live in .env next to this file. services: # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ---- # Source: https://caddyserver.com/docs/running (checked 2026-09-23) # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23) # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly. caddy: image: "caddy:2" container_name: "caddy" restart: "unless-stopped" ports: - "80:80" - "443:443" - "443:443/udp" volumes: - "./caddy:/etc/caddy" - "caddy-data:/data" - "caddy-config:/config" networks: proxy: ipv4_address: "172.30.0.2" # ---- Forgejo (git.example.org) ---- # Source: https://forgejo.org/docs/latest/admin/installation/docker/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/setup/reverse-proxy/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/config-cheat-sheet/ (checked 2026-09-23) # Source: https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/docker/root/etc/s6/openssh/setup (checked 2026-10-09) # Source: https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/docker/root/etc/templates/sshd_config (checked 2026-10-09) # Changed: Removed the documented '3000:3000' port; Caddy reaches forgejo-server:3000 on the proxy network. # Git over SSH on (dankhost.com/app/forgejo/): the documented '222:22' SSH port is published beside Caddy's 80 and 443. FORGEJO__server__DISABLE_SSH is false, and FORGEJO__server__SSH_DOMAIN and FORGEJO__server__SSH_PORT (from the cheat sheet) make the SSH clone address Forgejo prints match this file. # Added FORGEJO__server__ROOT_URL, set to https://git.example.org/, using the documented FORGEJO__[SECTION]__[KEY] variable form; the cheat sheet says to override ROOT_URL when internal and external URLs differ, as they do in Docker. # The documented container_name 'forgejo' and network 'forgejo' are replaced by the builder's names: the service runs as forgejo-server on the proxy network. # Uses the documented default SQLite database. The docs' PostgreSQL variant is on dankhost.com/app/forgejo/ (the SQLite / PostgreSQL switch above the compose file); their MySQL variant is not offered. # PORT OUTSIDE THE PROXY 222/tcp: Git over SSH, so you can clone and push with your SSH key. The container's own SSH server listens on 22, the right-hand side; SSH is not HTTP, so it cannot go through the proxy. forgejo-server: image: "codeberg.org/forgejo/forgejo:16" container_name: "forgejo-server" environment: USER_UID: "1000" USER_GID: "1000" FORGEJO__server__ROOT_URL: "https://git.example.org/" FORGEJO__server__DISABLE_SSH: "false" FORGEJO__server__SSH_DOMAIN: "git.example.org" FORGEJO__server__SSH_PORT: "222" restart: "always" volumes: - "./forgejo/forgejo:/data" - "/etc/localtime:/etc/localtime:ro" ports: - "222:22" # Git over SSH networks: proxy: {} networks: # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact. # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's # ipv4_address and in every trusted-proxy value to a free 172.x.0 range. proxy: ipam: config: - subnet: "172.30.0.0/24" ip_range: "172.30.0.128/25" gateway: "172.30.0.1" volumes: caddy-data: caddy-config:
With PostgreSQL
With Git over SSH on
The same file with Forgejo's SSH port published beside Caddy and labelled # PORT OUTSIDE THE PROXY, FORGEJO__server__DISABLE_SSH, FORGEJO__server__SSH_DOMAIN and FORGEJO__server__SSH_PORT set. Everything else is the off file, as the builder writes it for Forgejo alone on example.org.
# docker-compose.yml built at dankhost.com for: Forgejo # Each app block is its official compose definition. Only the names were prefixed with # the app slug (services, containers, volumes, bind folders, .env variables) so any set of # apps can share one file; other differences are listed under "Changed:" in each block. # Caddy publishes 80 and 443. The only other published ports, each labelled where # it is written: 222/tcp (Forgejo: Git over SSH). # Secrets live in .env next to this file. services: # ---- Caddy: the one reverse proxy, HTTPS certificates from Let's Encrypt ---- # Source: https://caddyserver.com/docs/running (checked 2026-09-23) # Source: https://github.com/dani-garcia/vaultwarden/wiki/Using-Docker-Compose (checked 2026-09-23) # Caddyfile goes in ./caddy/Caddyfile. Fixed address 172.30.0.2 so apps can trust it exactly. caddy: image: "caddy:2" container_name: "caddy" restart: "unless-stopped" ports: - "80:80" - "443:443" - "443:443/udp" volumes: - "./caddy:/etc/caddy" - "caddy-data:/data" - "caddy-config:/config" networks: proxy: ipv4_address: "172.30.0.2" # ---- Forgejo (git.example.org) ---- # Source: https://forgejo.org/docs/latest/admin/installation/docker/ (checked 2026-09-30) # Source: https://forgejo.org/docs/latest/admin/setup/reverse-proxy/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/config-cheat-sheet/ (checked 2026-09-23) # Source: https://forgejo.org/docs/latest/admin/installation/database-preparation/ (checked 2026-09-30) # Source: https://hub.docker.com/_/postgres (checked 2026-09-30) # Source: https://www.postgresql.org/support/versioning/ (checked 2026-09-30) # Source: https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/docker/root/etc/s6/openssh/setup (checked 2026-10-09) # Source: https://codeberg.org/forgejo/forgejo/src/tag/v16.0.5/docker/root/etc/templates/sshd_config (checked 2026-10-09) # Changed: Removed the documented '3000:3000' port; Caddy reaches forgejo-server:3000 on the proxy network. # Git over SSH on (dankhost.com/app/forgejo/): the documented '222:22' SSH port is published beside Caddy's 80 and 443. FORGEJO__server__DISABLE_SSH is false, and FORGEJO__server__SSH_DOMAIN and FORGEJO__server__SSH_PORT (from the cheat sheet) make the SSH clone address Forgejo prints match this file. # Added FORGEJO__server__ROOT_URL, set to https://git.example.org/, using the documented FORGEJO__[SECTION]__[KEY] variable form; the cheat sheet says to override ROOT_URL when internal and external URLs differ, as they do in Docker. # The documented container_name 'forgejo' and network 'forgejo' are replaced by the builder's names: the service runs as forgejo-server on the proxy network. # Uses the PostgreSQL variant from the 'PostgreSQL database' section of the same docs page: the five FORGEJO__database__ variables on server, depends_on db, and a db service running postgres:14, the major version the docs pin. # The documented password 'forgejo' (in FORGEJO__database__PASSWD and POSTGRES_PASSWORD) is replaced by DB_PASSWORD, a random secret in .env; the documented user and database name, forgejo, are kept. # db sits only on the internal network it shares with server, publishes no port and is not on the proxy network; server reaches it as db:5432, the address the docs use. # PORT OUTSIDE THE PROXY 222/tcp: Git over SSH, so you can clone and push with your SSH key. The container's own SSH server listens on 22, the right-hand side; SSH is not HTTP, so it cannot go through the proxy. forgejo-server: image: "codeberg.org/forgejo/forgejo:16" container_name: "forgejo-server" environment: USER_UID: "1000" USER_GID: "1000" FORGEJO__database__DB_TYPE: "postgres" FORGEJO__database__HOST: "db:5432" FORGEJO__database__NAME: "forgejo" FORGEJO__database__USER: "forgejo" FORGEJO__database__PASSWD: "${FORGEJO_DB_PASSWORD}" FORGEJO__server__ROOT_URL: "https://git.example.org/" FORGEJO__server__DISABLE_SSH: "false" FORGEJO__server__SSH_DOMAIN: "git.example.org" FORGEJO__server__SSH_PORT: "222" restart: "always" volumes: - "./forgejo/forgejo:/data" - "/etc/localtime:/etc/localtime:ro" depends_on: - "forgejo-db" ports: - "222:22" # Git over SSH networks: proxy: {} forgejo-backend: aliases: - "server" forgejo-db: image: "postgres:14" container_name: "forgejo-db" restart: "always" environment: POSTGRES_USER: "forgejo" POSTGRES_PASSWORD: "${FORGEJO_DB_PASSWORD}" POSTGRES_DB: "forgejo" volumes: - "./forgejo/postgres:/var/lib/postgresql/data" networks: forgejo-backend: aliases: - "db" networks: # Pinned so the trusted-proxy address given to each app (172.30.0.2) is exact. # If "docker compose up" reports "Pool overlaps", change 172.30.0 here, in Caddy's # ipv4_address and in every trusted-proxy value to a free 172.x.0 range. proxy: ipam: config: - subnet: "172.30.0.0/24" ip_range: "172.30.0.128/25" gateway: "172.30.0.1" forgejo-backend: internal: true volumes: caddy-data: caddy-config:
"222:22": “- '222:22'” Forgejo docs: Installation with Docker (docker-compose example, FORGEJO__section__KEY variables) checked 2026-10-09FORGEJO__server__DISABLE_SSH: "false": set to false, its documented default, instead of removed: the off file set it to true, and the docs say a removed variable leaves the value in app.ini: “DISABLE_SSH: false: Disable SSH feature when it’s not available.” Forgejo docs: Configuration Cheat Sheet (ROOT_URL, DISABLE_SSH) checked 2026-10-09 “It is not possible to use environment variables to remove an existing value, it must be done by editing the app.ini file.” Forgejo docs: Installation with Docker (docker-compose example, FORGEJO__section__KEY variables) checked 2026-10-09FORGEJO__server__SSH_DOMAIN: "git.example.org": the host name in the SSH clone address Forgejo prints on every repository page: “SSH_DOMAIN: %(DOMAIN)s: Domain name of this server, used for displayed clone URL.” Forgejo docs: Configuration Cheat Sheet (ROOT_URL, DISABLE_SSH) checked 2026-10-09FORGEJO__server__SSH_PORT: "222": the port in that address, the host port of the mapping: “SSH_PORT: 22: SSH port displayed in the clone URL.” Forgejo docs: Configuration Cheat Sheet (ROOT_URL, DISABLE_SSH) checked 2026-10-09- The variable names: “It is possible to add and modify configuration values by setting environment variables named in format FORGEJO__[SECTION]__[KEY].” Forgejo docs: Installation with Docker (docker-compose example, FORGEJO__section__KEY variables) checked 2026-10-09 All three keys sit under “Server (server)” in Forgejo docs: Configuration Cheat Sheet (ROOT_URL, DISABLE_SSH) checked 2026-10-09.
- Inside the container Forgejo's image runs OpenSSH, and its start script takes the port from the plain SSH_PORT / SSH_LISTEN_PORT variables, not from FORGEJO__server__SSH_PORT, so it keeps listening on 22, the right-hand side of the mapping. Do not add a plain SSH_PORT: it would move that server off 22. “SSH_PORT=${SSH_PORT:-"22"} \” “SSH_LISTEN_PORT=${SSH_LISTEN_PORT:-"${SSH_PORT}"} \” Forgejo v16.0.5: docker/root/etc/s6/openssh/setup (the image's sshd start script) checked 2026-10-09 “Port ${SSH_LISTEN_PORT}” Forgejo v16.0.5: docker/root/etc/templates/sshd_config checked 2026-10-09
Caddyfile save as caddy/Caddyfile
Caddy gets and renews the HTTPS certificate for git.example.org by itself once the DNS record points at your server and ports 80 and 443 reach it.
# Caddyfile built at dankhost.com. Save it as ./caddy/Caddyfile next to docker-compose.yml.
# Caddy gets and renews a Let's Encrypt certificate for each name below by itself,
# once the DNS records point at this server and ports 80 and 443 reach it.
# Forgejo
git.example.org {
reverse_proxy forgejo-server:3000
}
.env
With SQLite, the default
Forgejo needs no secret here; the builder adds nothing you have to fill in by hand.
# .env for Forgejo, from dankhost.com/app/forgejo/. Nothing here is secret. # Keep this file private (chmod 600). # None of the chosen apps needs a variable here.
With PostgreSQL
The secret is left blank here on purpose: a password printed on a public page is the same for everyone who copies it. Fill it with random letters and digits as in How to run it.
# .env for Forgejo, from dankhost.com/app/forgejo/. Fill the blank secret before starting. # Keep this file private (chmod 600). # Forgejo # 32 random letters and digits, for example from: tr -dc A-Za-z0-9 </dev/urandom | head -c 32 FORGEJO_DB_PASSWORD=
Changes from the official file
Besides prefixing every service, container, volume, folder and variable with forgejo (so any set of apps can share one file), these are all the differences from what the project documents:
With SQLite, the default
- Removed the documented '3000:3000' port; Caddy reaches forgejo-server:3000 on the proxy network.
- Removed the documented '222:22' SSH port, because in this file only Caddy publishes ports. Git works over HTTPS only, and FORGEJO__server__DISABLE_SSH is set to true (the cheat sheet's 'Disable SSH feature when it's not available') so Forgejo stops offering SSH clone addresses that would not work.
- Git over SSH on (dankhost.com/app/forgejo/): the documented '222:22' SSH port is published beside Caddy's 80 and 443. FORGEJO__server__DISABLE_SSH is false, and FORGEJO__server__SSH_DOMAIN and FORGEJO__server__SSH_PORT (from the cheat sheet) make the SSH clone address Forgejo prints match this file.
- Added FORGEJO__server__ROOT_URL, set to https://git.example.org/, using the documented FORGEJO__[SECTION]__[KEY] variable form; the cheat sheet says to override ROOT_URL when internal and external URLs differ, as they do in Docker.
- The documented container_name 'forgejo' and network 'forgejo' are replaced by the builder's names: the service runs as forgejo-server on the proxy network.
- Uses the documented default SQLite database. The docs' PostgreSQL variant is on dankhost.com/app/forgejo/ (the SQLite / PostgreSQL switch above the compose file); their MySQL variant is not offered.
Notes for Forgejo behind the proxy
- Git over SSH is off in this file, so clone and push over HTTPS: git clone https://git.example.org/<user>/<repo>.git. Git asks for your Forgejo user name and password, or an access token (Settings > Applications) if you use two-factor login. The Git over SSH switch at the top of the page gives the file with the SSH port.
- Git over SSH is on: add your SSH key in Forgejo and clone with the ssh:// address Forgejo prints, as under Git over SSH at the top of the page. Cloning over HTTPS keeps working too.
- The first visit opens Forgejo's initial configuration page, and it is open to whoever gets there first: open the address straight away, keep SQLite, check that the base URL reads https://git.example.org/, and create the administrator account on that page.
- The docs say ./forgejo/forgejo must be owned by the UID/GID in USER_UID/USER_GID (1000 here) or the container may not start. Run 'id -u' and 'id -g' and change both values if yours differ.
With PostgreSQL
- Removed the documented '3000:3000' port; Caddy reaches forgejo-server:3000 on the proxy network.
- Removed the documented '222:22' SSH port, because in this file only Caddy publishes ports. Git works over HTTPS only, and FORGEJO__server__DISABLE_SSH is set to true (the cheat sheet's 'Disable SSH feature when it's not available') so Forgejo stops offering SSH clone addresses that would not work.
- Git over SSH on (dankhost.com/app/forgejo/): the documented '222:22' SSH port is published beside Caddy's 80 and 443. FORGEJO__server__DISABLE_SSH is false, and FORGEJO__server__SSH_DOMAIN and FORGEJO__server__SSH_PORT (from the cheat sheet) make the SSH clone address Forgejo prints match this file.
- Added FORGEJO__server__ROOT_URL, set to https://git.example.org/, using the documented FORGEJO__[SECTION]__[KEY] variable form; the cheat sheet says to override ROOT_URL when internal and external URLs differ, as they do in Docker.
- The documented container_name 'forgejo' and network 'forgejo' are replaced by the builder's names: the service runs as forgejo-server on the proxy network.
- Uses the PostgreSQL variant from the 'PostgreSQL database' section of the same docs page: the five FORGEJO__database__ variables on server, depends_on db, and a db service running postgres:14, the major version the docs pin.
- The documented password 'forgejo' (in FORGEJO__database__PASSWD and POSTGRES_PASSWORD) is replaced by DB_PASSWORD, a random secret in .env; the documented user and database name, forgejo, are kept.
- db sits only on the internal network it shares with server, publishes no port and is not on the proxy network; server reaches it as db:5432, the address the docs use.
Notes for Forgejo behind the proxy
- Git over SSH is off in this file, so clone and push over HTTPS: git clone https://git.example.org/<user>/<repo>.git. Git asks for your Forgejo user name and password, or an access token (Settings > Applications) if you use two-factor login. The Git over SSH switch at the top of the page gives the file with the SSH port.
- Git over SSH is on: add your SSH key in Forgejo and clone with the ssh:// address Forgejo prints, as under Git over SSH at the top of the page. Cloning over HTTPS keeps working too.
- The first visit opens Forgejo's initial configuration page, and it is open to whoever gets there first: open the address straight away. Its database fields come from the FORGEJO__database__ variables (PostgreSQL, db:5432, forgejo), so leave them as they are; check that the base URL reads https://git.example.org/ and create the administrator account on that page.
- The docs say ./forgejo/forgejo must be owned by the UID/GID in USER_UID/USER_GID (1000 here) or the container may not start. Run 'id -u' and 'id -g' and change both values if yours differ.
- postgres:14 is the version the docs pin, but PostgreSQL 14 gets its last release on November 12, 2026 (PostgreSQL versioning policy), and moving to a newer major version later means a dump and restore (see Update it). For a new instance you can write a newer major into the tag before the first start, for example postgres:18: Forgejo supports 14 and later. From 18 on the image keeps its data one level up, so change the volume line to ./postgres:/var/lib/postgresql at the same time.
How to run it
With SQLite, the default
- At your DNS provider, add an A record named
giton your domain pointing at the server's public IP address, and forward TCP 80, TCP 443 and UDP 443 to it. - Save the three files in one folder:
docker-compose.ymland.envside by side, the Caddyfile at./caddy/Caddyfile. Replaceexample.orgwith your domain in the Caddyfile, the compose file and the .env, or let the builder do it. - Nothing in
.envneeds filling in;chmod 600 .envall the same. - Start it:
docker compose up -d docker compose logs -f caddy # watch the certificate arrive
- Open the new address (
git.plus your domain) in a browser and follow the notes above.
With PostgreSQL
- At your DNS provider, add an A record named
giton your domain pointing at the server's public IP address, and forward TCP 80, TCP 443 and UDP 443 to it. - Save the three files in one folder:
docker-compose.ymland.envside by side, the Caddyfile at./caddy/Caddyfile. Replaceexample.orgwith your domain in the Caddyfile, the compose file and the .env. - Fill the blank
FORGEJO_DB_PASSWORDin.env. On the server,tr -dc A-Za-z0-9 </dev/urandom | head -c 32prints 32 random letters and digits. Thenchmod 600 .env. - Start it:
docker compose up -d docker compose logs -f caddy # watch the certificate arrive
- Open the new address (
git.plus your domain) in a browser and follow the notes above.
Back it up
With SQLite, the default
Forgejo's upgrade guide calls a point-in-time copy of all the storage Forgejo uses the reliable backup, and says only a shut-down Forgejo guarantees a consistent state. In this compose everything (app.ini, the SQLite database, repositories and uploads) is in one folder.
Below is the BACKUP.md the builder writes next to the compose file above: which of its folders and volumes hold data, what to copy with which container stopped, and a restore check. Pick more apps in the builder and it covers them all in one file.
# BACKUP.md built at dankhost.com for: Forgejo
What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.
The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.
Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.
## Before you start
BACKUP=/mnt/backup/selfhost # change this: a disk or machine other than this server's system disk
mkdir -p "$BACKUP"
## Every time: the three stack files
tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy
.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.
## Caddy (the reverse proxy)
Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.
- caddy-data (named volume, /data in caddy)
BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.
Copy (Caddy keeps serving while you copy):
docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data
Restore check:
tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"
Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)
## Forgejo
Forgejo's upgrade guide calls a point-in-time copy of all the storage Forgejo uses the reliable backup, and says only a shut-down Forgejo guarantees a consistent state. In this compose everything (app.ini, the SQLite database, repositories and uploads) is in one folder.
What this compose mounts:
- ./forgejo/forgejo (/data in forgejo-server)
BACK UP: Forgejo's whole /data: app.ini with the instance's secret keys, the SQLite database, the git repositories and uploaded files.
Forgejo also has 'forgejo dump', which zips files and database into one file. The upgrade guide warns that the SQL copy inside has long-standing bugs when loaded into a new database, and that with SQLite no separate dump is needed because the database file is in the zip. To make one as well, run this before step 1 (the image runs Forgejo as the git user; the zip lands in ./forgejo/forgejo and so goes into the copy):
docker compose exec -u git -w /data forgejo-server forgejo dump -c /data/gitea/conf/app.ini
1. Stop forgejo-server. Forgejo's guide: shutting Forgejo down during the backup is the way to be sure its state is consistent.
docker compose stop forgejo-server
2. Copy while forgejo-server is stopped:
tar czf "$BACKUP/forgejo-forgejo.tar.gz" ./forgejo/forgejo
3. Start it again:
docker compose start forgejo-server
Restore check:
tar tzf "$BACKUP/forgejo-forgejo.tar.gz" > /dev/null && echo OK
Put a copy back (with forgejo-server stopped):
tar xzf "$BACKUP/forgejo-forgejo.tar.gz" # recreates ./forgejo/forgejo; move the old folder aside first
Stop it, put ./forgejo/forgejo back, start it. Then run the check Forgejo's guide gives for verifying an instance:
docker compose exec -u git forgejo-server forgejo doctor check --all
Sources:
- Forgejo docs: Upgrade guide (Backup, Verify Forgejo works): https://forgejo.org/docs/latest/admin/upgrade/ (checked 2026-09-24)
- Forgejo docs: Command-line interface (dump): https://forgejo.org/docs/latest/admin/command-line/ (checked 2026-09-24)
With PostgreSQL
Forgejo's upgrade guide calls a point-in-time copy of all the storage Forgejo uses the reliable backup, says only a shut-down Forgejo guarantees a consistent state, and names a psql dump next to forgejo dump. With PostgreSQL the database is in its own container: stop Forgejo, dump the database with pg_dump, then copy ./forgejo.
Below is the BACKUP.md for the PostgreSQL version of the compose file above, written by the same code as the builder's: which of its folders and volumes hold data, the dump command the project documents, rewritten for this file's service names, what to copy with which container stopped, and a restore check.
# BACKUP.md built at dankhost.com for: Forgejo
What to copy from the docker-compose.yml built with this file, the database dump each project documents (rewritten for the service names in that file), what to copy with which container stopped, and how to check the result. Run every command in the folder that holds docker-compose.yml.
The folders are owned by the containers' users: put sudo in front of tar if it says "Permission denied". Named volumes live under /var/lib/docker/volumes, not next to the compose file, so they are copied through a throwaway ubuntu container (Docker's documented --volumes-from method). tar makes a full copy each run; for large folders an incremental tool (restic, borg, rsync) saves time and space.
Never run "docker compose down -v" on this file: it deletes the named volumes of every app in it.
## Before you start
BACKUP=/mnt/backup/selfhost # change this: a disk or machine other than this server's system disk
mkdir -p "$BACKUP"
## Every time: the three stack files
tar czf "$BACKUP/stack-files.tar.gz" docker-compose.yml .env caddy
.env holds the database passwords and secret keys the apps were set up with; keep this archive as private as the data.
## Caddy (the reverse proxy)
Caddy's docs: 'The data directory must not be treated as a cache.' It holds the TLS certificates and their private keys; without it Caddy has to ask Let's Encrypt for every certificate again.
- caddy-data (named volume, /data in caddy)
BACK UP: TLS certificates, private keys, OCSP staples.
- caddy-config (named volume, /config in caddy)
SKIP: the last active configuration, kept for 'caddy run --resume', which this setup does not use: it starts from the Caddyfile.
- ./caddy (/etc/caddy in caddy)
IN stack-files.tar.gz: the Caddyfile, copied with the stack files above.
Copy (Caddy keeps serving while you copy):
docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu tar cvf /backup/caddy-data.tar /data
Restore check:
tar tf "$BACKUP/caddy-data.tar" > /dev/null && echo OK
docker run --rm --volumes-from caddy -v "$BACKUP":/backup ubuntu bash -c "cd /data && tar xvf /backup/caddy-data.tar --strip 1"
Sources:
- Caddy docs: Conventions, Data directory: https://caddyserver.com/docs/conventions#data-directory (checked 2026-09-24)
- Docker docs: Volumes, Back up, restore, or migrate data volumes: https://docs.docker.com/engine/storage/volumes/#back-up-restore-or-migrate-data-volumes (checked 2026-09-24)
## Forgejo
Forgejo's upgrade guide calls a point-in-time copy of all the storage Forgejo uses the reliable backup, says only a shut-down Forgejo guarantees a consistent state, and names a psql dump next to forgejo dump. With PostgreSQL the database is in its own container: stop Forgejo, dump the database with pg_dump, then copy ./forgejo.
What this compose mounts:
- ./forgejo/forgejo (/data in forgejo-server)
BACK UP: Forgejo's /data: app.ini with the instance's secret keys and database settings, the git repositories and uploaded files. The database itself is in PostgreSQL.
- ./forgejo/postgres (/var/lib/postgresql/data in forgejo-db)
COVERED BY THE COMMAND BELOW: PostgreSQL's data files; the pg_dump below is the copy to keep. Copy this folder itself only with db stopped.
1. Stop forgejo-server. Forgejo's guide: shutting Forgejo down during the backup is the way to be sure its state is consistent. The database keeps running for the dump.
docker compose stop forgejo-server
2. Database dump for forgejo-db:
docker compose exec -T forgejo-db pg_dump -U forgejo forgejo > "$BACKUP/forgejo-db.sql"
pg_dump runs inside the database container as forgejo, the user the compose file creates, and writes the forgejo database as SQL. The upgrade guide advises a database dump like this one rather than the SQL copy inside forgejo dump's zip, which it says has long-standing bugs when loaded into a new database.
3. Copy while forgejo-server is stopped:
tar czf "$BACKUP/forgejo-forgejo.tar.gz" ./forgejo/forgejo
4. Start it again:
docker compose start forgejo-server
Restore check:
grep -c 'PostgreSQL database dump complete' "$BACKUP/forgejo-db.sql" # 1 means pg_dump finished
tar tzf "$BACKUP/forgejo-forgejo.tar.gz" > /dev/null && echo OK
Put a copy back (with forgejo-server stopped):
tar xzf "$BACKUP/forgejo-forgejo.tar.gz" # recreates ./forgejo/forgejo; move the old folder aside first
The dump goes into an empty database. Stop everything, put ./forgejo/forgejo back and move ./forgejo/postgres aside; then start only db (on first start it creates an empty forgejo database), load the dump, and start the rest:
docker compose up -d forgejo-db
until docker compose exec -T forgejo-db pg_isready -h 127.0.0.1 -U forgejo; do sleep 2; done # waits until the first-start setup is over
docker compose exec -T forgejo-db psql -U forgejo -d forgejo --set ON_ERROR_STOP=on < "$BACKUP/forgejo-db.sql"
docker compose up -d
Then run the check Forgejo's guide gives for verifying an instance:
docker compose exec -u git forgejo-server forgejo doctor check --all
Sources:
- Forgejo docs: Upgrade guide (Backup: forgejo dump and a psql dump, Verify Forgejo works): https://forgejo.org/docs/latest/admin/upgrade/ (checked 2026-09-30)
- PostgreSQL docs: pg_dump: https://www.postgresql.org/docs/current/app-pgdump.html (checked 2026-09-30)
Update it
With SQLite, the default
What docker compose pull does depends only on how each image line in the compose file above is tagged. For Forgejo as this page writes it:
| Service | Image | How it is pinned | What docker compose pull does |
|---|---|---|---|
caddy | caddy:2 | Major version only (tag 2) | Takes the newest image tagged 2: minor and patch releases of 2, never 3. A new major version needs a tag edit. |
forgejo-server | codeberg.org/forgejo/forgejo:16 | Major version only (tag 16) | Takes the newest image tagged 16: minor and patch releases of 16, never 17. A new major version needs a tag edit. |
What Forgejo's docs say about updating
Forgejo's upgrade guide: make a full backup first (it calls this a requirement when moving to a new stable release), read the notes for the version you are upgrading from, then go straight to the latest release by replacing the image. Forgejo migrates its database itself when the new version starts.
- Forgejo follows semantic versioning since 7.0.0: no breaking change unless the first number changes. The tag 16 here takes only those non-breaking releases; moving to 17 means editing the tag, after reading what the guide lists for it.
- Before stopping the old version the guide has you empty Forgejo's queues, here:
docker compose exec -u git forgejo-server forgejo manager flush-queues
- Forgejo stores its database version and refuses an accidental downgrade: the way back is the backup.
- If an upgrade across several versions goes wrong, the guide suggests upgrading to the last release of each series in turn and checking each one. After the upgrade, verify the instance with:
docker compose exec -u git forgejo-server forgejo doctor check --all
- Forgejo under Docker needs Docker 20.10.6 or later.
The steps
- Back up first, as in Back it up above. An update can migrate Forgejo's data on its first start; the copy is the way back.
- Download the new images. Running containers are not touched yet:
docker compose pull
- Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:
docker compose up -d
- Watch Forgejo start (Ctrl+C stops following the log, not the app):
docker compose logs -f forgejo-server
- Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:
docker image prune
With PostgreSQL
What docker compose pull does depends only on how each image line in the compose file above is tagged. For Forgejo as this page writes it:
| Service | Image | How it is pinned | What docker compose pull does |
|---|---|---|---|
caddy | caddy:2 | Major version only (tag 2) | Takes the newest image tagged 2: minor and patch releases of 2, never 3. A new major version needs a tag edit. |
forgejo-server | codeberg.org/forgejo/forgejo:16 | Major version only (tag 16) | Takes the newest image tagged 16: minor and patch releases of 16, never 17. A new major version needs a tag edit. |
forgejo-db database | postgres:14 | Major version only (tag 14) | Takes the newest image tagged 14: minor and patch releases of 14, never 15. A new major version needs a tag edit. |
Do not raise the major version of forgejo-db by editing its tag. Keep its tag, 14, as it is when you update Forgejo.
PostgreSQL's docs: a new major version may change how data is stored on disk, so a data folder written by an older major version will not start under a newer one (the server refuses it). Moving needs a dump and restore (pg_dumpall, then load the dump into the new version) or pg_upgrade. Minor releases of the same major version never change the storage format. Source: PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30
What Forgejo's docs say about updating
Forgejo's upgrade guide: make a full backup first (it calls this a requirement when moving to a new stable release), read the notes for the version you are upgrading from, then go straight to the latest release by replacing the image. Forgejo migrates its database itself when the new version starts.
- Forgejo follows semantic versioning since 7.0.0: no breaking change unless the first number changes. The tag 16 here takes only those non-breaking releases; moving to 17 means editing the tag, after reading what the guide lists for it.
- Before stopping the old version the guide has you empty Forgejo's queues, here:
docker compose exec -u git forgejo-server forgejo manager flush-queues
- Forgejo stores its database version and refuses an accidental downgrade: the way back is the backup.
- If an upgrade across several versions goes wrong, the guide suggests upgrading to the last release of each series in turn and checking each one. After the upgrade, verify the instance with:
docker compose exec -u git forgejo-server forgejo doctor check --all
- Forgejo under Docker needs Docker 20.10.6 or later.
- Forgejo and PostgreSQL are updated separately, one tag at a time. The db tag, postgres:14, takes every 14.x release on docker compose pull; PostgreSQL says minor releases never change the storage format, so that is safe.
- A new PostgreSQL major version cannot open the data folder of the old one: PostgreSQL's Upgrading a PostgreSQL Cluster page says to dump the data from the old version and restore it into the new one (or use pg_upgrade). With this file: stop Forgejo, dump, stop db and move its folder aside, edit the db tag (for 18 and later also the mount, see the notes above), start db alone, load the dump, start the rest:
docker compose stop forgejo-server docker compose exec -T forgejo-db pg_dump -U forgejo forgejo > forgejo-pg14.sql docker compose stop forgejo-db && mv forgejo/postgres forgejo/postgres-14 docker compose up -d forgejo-db # after editing the tag until docker compose exec -T forgejo-db pg_isready -h 127.0.0.1 -U forgejo; do sleep 2; done # waits until the first-start setup is over docker compose exec -T forgejo-db psql -U forgejo -d forgejo --set ON_ERROR_STOP=on < forgejo-pg14.sql docker compose up -d
- Keep forgejo/postgres-14 until Forgejo has run well for a while: putting it back with the old tag is the way back.
The steps
- Back up first, as in Back it up above. An update can migrate Forgejo's data on its first start and its database with it; the copy is the way back.
- Download the new images. Running containers are not touched yet:
docker compose pull
- Recreate the containers whose image changed. Volumes and bind-mounted folders stay as they are:
docker compose up -d
- Watch Forgejo start (Ctrl+C stops following the log, not the app):
docker compose logs -f forgejo-server
- Optional: remove the old images the pull left without a tag. This covers every stack on the machine, not only this one:
docker image prune
Locked out? Reset the admin password
Sets a new password for a Forgejo user with Forgejo's own admin CLI, which the docs say to run as the git user.
- List the users if you need the exact name: Source: Forgejo docs: Command-line interface (admin user change-password) read 2026-10-03; Forgejo docs: Installation from binary, General hints (run the CLI as the git user) read 2026-10-03
docker compose exec -u git forgejo-server forgejo admin user list
- Change the password. Add --must-change-password to make the user pick a new one at the next login. Source: Forgejo docs: Command-line interface (admin user change-password) read 2026-10-03; Forgejo docs: Installation from binary, General hints (run the CLI as the git user) read 2026-10-03
docker compose exec -u git forgejo-server forgejo admin user change-password --username '<admin user>' --password '<new password>'
Run Forgejo Actions (CI)
Forgejo Actions runs the workflows in a repository's .forgejo/workflows folder, but Forgejo itself does not run the jobs: a separate program, Forgejo Runner, fetches them from Forgejo and runs them, and until one is registered, pushes start nothing. Below is the runner half of Forgejo's own Docker Compose example (a Docker-in-Docker daemon, a one-shot service that writes the runner's config file, and the runner), set up to sit beside the Forgejo above. Source: Forgejo docs: Forgejo Actions administrator guide (Forgejo Runner, Enabling/Disabling; runner-installation/ redirects here) checked 2026-10-01; forgejo/runner repository: examples/docker-compose (compose-forgejo-and-runner.yml, compose-demo-workflow.yml, README) checked 2026-10-01
Forgejo's README for this example opens with: "this example is just what it is: an example. It is not fit to be used in production. It shows how Forgejo, the Forgejo runner can work together with Docker in Docker." The page keeps the example's choices and lists every change; it adds no hardening of its own. Source: forgejo/runner repository: examples/docker-compose (compose-forgejo-and-runner.yml, compose-demo-workflow.yml, README) checked 2026-10-01
compose.override.yaml next to docker-compose.yml
# compose.override.yaml for Forgejo: Run Forgejo Actions (CI). From dankhost.com/app/forgejo/. # Save it next to docker-compose.yml: docker compose reads both files and merges them. # No service here publishes a port or joins the proxy network. # Source: https://code.forgejo.org/forgejo/runner/src/branch/main/examples/docker-compose (checked 2026-10-01) # Source: https://forgejo.org/docs/latest/admin/actions/installation/docker/ (checked 2026-10-01) # Source: https://forgejo.org/docs/latest/admin/actions/registration/ (checked 2026-10-01) # Changed: Only the runner side of the example is used: docker-in-docker, runner-register and runner-daemon. Its forgejo service (Forgejo 11.0 with a replaced start command that registers the runner from a shared secret and creates a root user) is left out: Forgejo is the forgejo-server of docker-compose.yml, unchanged except that it also joins forgejo-actions. # Names get the forgejo- prefix like the rest of the file: docker-in-docker, runner-register, runner-daemon and the docker_certs volume become forgejo-docker-in-docker, forgejo-runner-register, forgejo-runner-daemon and forgejo-docker-certs; runner-register's DOCKER_HOST follows the rename (tcp://forgejo-docker-in-docker:2376). # The links to docker-in-docker and forgejo are replaced by one network, forgejo-actions, that the three services and forgejo-server share. It is not the proxy network, and no service in this file publishes a port. # docker-in-docker gets the network alias docker: the runner and the jobs reach it as tcp://docker:2376, and the example's own comment says its TLS certificates are only valid for docker or localhost. # docker-in-docker gets restart: unless-stopped, as in the docker-compose.yml on Forgejo's Installation with Docker page for the runner; the example gives it no restart policy, so after a reboot the runner would come back without its Docker daemon. # The bind folder /srv/runner-data becomes ./forgejo/runner, next to Forgejo's ./forgejo/forgejo. # In the connection written into config.yml, url http://forgejo:3000 becomes http://forgejo-server:3000, and the {UUID} and {SHARED_SECRET} placeholders become ${FORGEJO_RUNNER_UUID} and ${FORGEJO_RUNNER_TOKEN} from .env, filled from Forgejo's Create new runner dialog (the registration the docs recommend) instead of a secret registered with forgejo-cli. services: # forgejo-server from docker-compose.yml also joins forgejo-actions; everything else about it stays as it is there. forgejo-server: networks: forgejo-actions: {} forgejo-docker-in-docker: image: "data.forgejo.org/oci/docker:dind" hostname: "docker" privileged: true restart: "unless-stopped" environment: DOCKER_TLS_CERTDIR: "/certs" DOCKER_HOST: "docker-in-docker" volumes: - "forgejo-docker-certs:/certs" networks: forgejo-actions: aliases: - "docker" forgejo-runner-register: image: "data.forgejo.org/forgejo/runner:13.2.0" user: "0:0" environment: DOCKER_HOST: "tcp://forgejo-docker-in-docker:2376" volumes: - "./forgejo/runner:/data" command: >- bash -ec ' if [ -e config.yml ] ; then echo "config.yml already exists"; exit 0; fi; forgejo-runner generate-config > config.yml ; sed -i -e "s| level: info| level: debug|" config.yml ; sed -i -e "s| labels: \[\]| labels: [\"docker-cli:docker://code.forgejo.org/oci/docker:cli\", \"node:docker://code.forgejo.org/oci/node:lts\"]|" 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 ; sed -i -e "s| connections:| connections:\n default:\n url: http://forgejo-server:3000\n uuid: ${FORGEJO_RUNNER_UUID}\n token: ${FORGEJO_RUNNER_TOKEN}|" config.yml ; chown -R 1000:1000 /data ' networks: forgejo-actions: {} forgejo-runner-daemon: image: "data.forgejo.org/forgejo/runner:13.2.0" restart: "unless-stopped" environment: DOCKER_HOST: "tcp://docker:2376" DOCKER_CERT_PATH: "/certs/client" DOCKER_TLS_VERIFY: "1" volumes: - "./forgejo/runner:/data" - "forgejo-docker-certs:/certs" depends_on: - "forgejo-runner-register" command: "forgejo-runner --config config.yml daemon" networks: forgejo-actions: {} networks: forgejo-actions: {} volumes: forgejo-docker-certs:
.env two lines to add
# Add to the .env next to docker-compose.yml (Forgejo: Run Forgejo Actions (CI)). # Fill both from the dialog Forgejo shows after "Create new runner", then chmod 600 .env. FORGEJO_RUNNER_UUID= FORGEJO_RUNNER_TOKEN=
Register the runner and start it
- Get Forgejo running with the files above and log in as its administrator. Open /admin/actions/runners (Site administration, then Actions, then Runners). The registration guide: a runner created there "will execute workflows from all repositories on the Forgejo instance"; one created at /{owner}/{repository}/settings/actions/runners runs that one repository's only, and /org/{org}/settings/actions/runners or /user/settings/actions/runners an organisation's or a user's. The security guide says that the tightest registration reduces the scope of the risk. Source: Forgejo docs: Forgejo Runner Registration (interactive registration) checked 2026-10-01; Forgejo docs: Securing Forgejo Actions Deployments checked 2026-10-01
- Press Create new runner, give it a name and a description, and press Create. In the guide's words, "a unique identifier (UUID) and a confidential secret (Token) will be displayed for the new runner". Add both to .env (two new lines; keep the file at chmod 600): Source: Forgejo docs: Forgejo Runner Registration (interactive registration) checked 2026-10-01
FORGEJO_RUNNER_UUID=the-uuid-forgejo-shows FORGEJO_RUNNER_TOKEN=the-token-forgejo-shows
- Save compose.override.yaml (above) in the same folder as docker-compose.yml. docker compose reads an override file with that name next to the main file without being told, so every docker compose command, the update steps above included, covers both. Source: Docker docs: Merge Compose files (compose.override.yaml is read by default) checked 2026-10-01; compose-go (the loader docker compose uses): DefaultFileNames and DefaultOverrideFileNames checked 2026-10-01
- Start it. forgejo-runner-register runs once: it runs forgejo-runner generate-config, applies the example's edits and writes ./forgejo/runner/config.yml with your UUID and token, then exits; forgejo-server is recreated on the extra network; the Docker daemon and the runner start. Source: forgejo/runner repository: examples/docker-compose (compose-forgejo-and-runner.yml, compose-demo-workflow.yml, README) checked 2026-10-01
docker compose up -d docker compose logs forgejo-runner-register docker compose logs -f forgejo-runner-daemon
- Reload /admin/actions/runners: the runner is listed there, with the labels docker-cli and node from its config file. If .env was still blank at the first start, config.yml has an empty uuid and token and the register step will not rewrite it (it stops when config.yml exists): delete ./forgejo/runner/config.yml and run docker compose up -d again. Source: forgejo/runner repository: examples/docker-compose (compose-forgejo-and-runner.yml, compose-demo-workflow.yml, README) checked 2026-10-01; Forgejo docs: Forgejo Runner Registration (interactive registration) checked 2026-10-01
- Test it with the example's own demo workflow, written as compose-demo-workflow.yml writes it (one line of YAML in flow style): push it as .forgejo/workflows/demo.yml to a repository, then open the repository's Actions tab. The job checks out the code and prints All Good. runs-on must name a label the runner has; the quick start says a run that warns no matching runner is online most likely has the wrong runs-on. Source: forgejo/runner repository: examples/docker-compose (compose-forgejo-and-runner.yml, compose-demo-workflow.yml, README) checked 2026-10-01; Forgejo docs: Actions quick start (Units > Overview, first workflow) checked 2026-10-01
{ on: [push], jobs: { test: { runs-on: node, steps: [ {uses: https://code.forgejo.org/actions/checkout@v4}, { run: echo All Good } ] } } }
The runner's config file ./forgejo/runner/config.yml
The docs' configuration reference: "All Forgejo Runner configuration options are documented in the default configuration file in YAML comments", and the install procedures generate it with forgejo-runner generate-config so it matches the runner version. Below is that file as runner 13.2.0 (the version the example pins) prints it, with the example's seven sed edits applied, as forgejo-runner-register writes it. Every other line is the generated default. Source: Forgejo docs: Forgejo Runner Configuration (labels, configuration file reference) checked 2026-10-01; forgejo/runner v13.2.0: config.example.yaml, the file forgejo-runner generate-config prints checked 2026-10-01; forgejo/runner repository: examples/docker-compose (compose-forgejo-and-runner.yml, compose-demo-workflow.yml, README) checked 2026-10-01
What the edits change:
- log level info becomes debug.
- labels [] becomes docker-cli (image code.forgejo.org/oci/docker:cli) and node (code.forgejo.org/oci/node:lts). A workflow's runs-on picks one; with a docker label "the runner will execute all the steps, as root, within a container created from that image".
- container network "" becomes host: job containers use the network of the Docker-in-Docker container they run in, instead of the new network per job that the default creates.
- runner envs gets DOCKER_HOST, DOCKER_TLS_VERIFY and DOCKER_CERT_PATH, so docker commands in a job talk to the Docker-in-Docker daemon over TLS. The generated file's two sample variables (A_TEST_ENV_NAME_1 and _2) stay, as in the example.
- container options gets -v /certs/client:/certs/client, which mounts the TLS client certificates into every job container.
- container valid_volumes [] becomes a list with /certs/client alone, the one volume jobs are allowed to mount.
- server connections gets one connection, default, with the url, uuid and token.
# Example configuration file, it's safe to copy this as the default config file without any modification.
# You don't have to copy this file to your instance,
# just run `forgejo-runner generate-config > config.yaml` to generate a config file.
#
# The value of level or job_level can be trace, debug, info, warn, error or fatal
#
log:
#
# What is displayed in the output of the runner process but not sent
# to the Forgejo instance.
#
level: debug
#
# What is sent to the Forgejo instance and therefore
# visible in the web UI for a given job.
#
job_level: info
runner:
# Where to store the registration result.
file: .runner
# Execute how many tasks concurrently at the same time.
capacity: 1
# Extra environment variables to run jobs.
envs:
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_VERIFY: 1
DOCKER_CERT_PATH: /certs/client
A_TEST_ENV_NAME_1: a_test_env_value_1
A_TEST_ENV_NAME_2: a_test_env_value_2
# Extra environment variables to run jobs from a file.
# It will be ignored if it's empty or the file doesn't exist.
env_file: .env
# The timeout for a job to be finished.
# Please note that the Forgejo instance also has a timeout (3h by default) for the job.
# So the job could be stopped by the Forgejo instance if its timeout is shorter than this.
timeout: 3h
# The timeout for the runner to wait for running jobs to finish when
# shutting down because a TERM or INT signal has been received. Any
# running jobs that haven't finished after this timeout will be
# canceled.
# If unset or zero, the jobs will be canceled immediately.
shutdown_timeout: 3h
# Whether skip verifying the TLS certificate of the instance.
insecure: false
# The timeout for fetching the job from the Forgejo instance.
fetch_timeout: 30s
# The interval for fetching the job from the Forgejo instance.
fetch_interval: 2s
# The interval for reporting the job status and logs to the Forgejo instance.
report_interval: 1s
# At the end of a job, retry configuration for sending logs to remote.
# report_retry:
# # Maximum number of retry attempts.
# max_retries: 10
# # Initial delay between retries. Delay between retries doubles up to `max_delay`.
# initial_delay: 100ms
# # Maximum delay between retries, defaults to 0, 0 is treated as no maximum.
# max_delay: 0
# The labels of a runner are used to determine which jobs the runner can run and how to run them.
# Like: ["macos-arm64:host", "ubuntu-latest:docker://node:20-bookworm", "ubuntu-22.04:docker://node:20-bookworm"]
# If it's empty when registering, it will ask for inputting labels.
# If it's empty when executing the `daemon`, it will use labels in the `.runner` file.
#
# A docker label may carry options as a query string. `platform` sets the OS/architecture
# passed to the container runtime when pulling and creating images, which is useful on hosts
# (e.g. FreeBSD, macOS) that can run images for several platforms. The value must use the names
# Docker uses (the values accepted by `docker --platform`), e.g. linux/amd64, linux/arm64, linux/386:
# labels: ["ubuntu-latest:docker://node:20-bookworm?platform=linux/amd64"]
#
# The same can be expressed with the more explicit mapping form:
# labels:
# freebsd-15:
# backend: docker
# backend-options:
# image: ghcr.io/freebsd/freebsd-runtime:15.0
# platform: freebsd/amd64
labels: ["docker-cli:docker://code.forgejo.org/oci/docker:cli", "node:docker://code.forgejo.org/oci/node:lts"]
cache:
#
# When enabled, workflows will be given the ACTIONS_CACHE_URL environment variable
# used by the https://code.forgejo.org/actions/cache action. The server at this
# URL must implement a compliant REST API, and it must also be reachable from
# the container or host running the workflows.
#
# See also https://forgejo.org/docs/next/user/actions/advanced-features/#cache
#
# When it is not enabled, none of the following options apply.
#
# It works as follows:
#
# - the workflow is given a one-time use ACTIONS_CACHE_URL
# - a cache proxy listens to ACTIONS_CACHE_URL
# - the cache proxy securely communicates with the cache server using
# a shared secret
#
enabled: true
#
#######################################################################
#
# Only used for the internal cache server.
#
# If external_server is not set, the Forgejo runner will spawn a
# cache server that will be used by the cache proxy.
#
#######################################################################
#
# The port being bound by the internal cache server.
# 0 means to use a random available port.
#
port: 0
#
# The directory to store the cache data.
#
# If empty, the cache data will be stored in $HOME/.cache/actcache.
#
dir: ""
#
#######################################################################
#
# Only used for the external cache server.
#
# If external_server is set, the internal cache server is not
# spawned.
#
#######################################################################
#
# The URL of the cache server. The URL should generally end with
# "/". The cache proxy will forward requests to the external
# server. The requests are authenticated with the "secret" that is
# shared with the external server.
#
external_server: ""
#
# The shared cache secret used to secure the communications between
# the cache proxy and the cache server.
#
# If empty, it will be generated to a new secret automatically when
# the server starts, and it will stay the same until it restarts.
#
# `secret` and `secret_url` are mutually exclusive.
#
secret: ""
#
# The secret for securing the cache can alternatively be loaded from a URL.
# Currently, only file URLs can be resolved. Example:
# `file:/path/to/secret.txt`.
#
# `secret_url` supports a single placeholder: `$CREDENTIALS_DIRECTORY`. If
# the environment variable `CREDENTIALS_DIRECTORY` exists, the placeholder is
# replaced with the value of `CREDENTIALS_DIRECTORY`. Otherwise, it is
# retained.
#
# Example: file:$CREDENTIALS_DIRECTORY/secret.txt
#
# `secret` and `secret_url` are mutually exclusive.
#
secret_url: ""
#
#######################################################################
#
# Common to the internal and external cache server
#
#######################################################################
#
# The IP or hostname (195.84.20.30 or example.com) to use when constructing
# ACTIONS_CACHE_URL which is the URL of the cache proxy.
#
# If empty, it will be detected automatically.
#
# It may be impossible to figure out the host automatically if the containers
# or host running the workflows reside on a different network than the Forgejo
# runner. For example, if the Docker server used to create containers is not
# running on the same host as the Forgejo runner.
# In that case you can specify which IP or hostname to use to reach the
# internal cache server created by the Forgejo runner.
#
host: ""
#
# The port bound by the internal cache proxy.
# 0 means to use a random available port.
#
proxy_port: 0
#
# Overrides the ACTIONS_CACHE_URL variable passed to workflow
# containers. The URL should generally not end with "/". This should only
# be used if the runner host is not reachable from the workflow containers
# and requires further setup.
#
actions_cache_url_override: ""
container:
# Specifies the network to which the container will connect.
# Could be `host`, `bridge` or the name of a custom network.
# If it's empty, create a network automatically.
network: host
# Whether to create networks with IPv6 enabled. Requires the Docker daemon to be set up accordingly.
# Only takes effect if "network" is set to "".
enable_ipv6: false
# Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
privileged: false
# And other options to be used when the container is started (e.g., --volume /etc/ssl/certs:/etc/ssl/certs:ro).
options: -v /certs/client:/certs/client
# The parent directory of a job's working directory.
# If it's empty, /workspace will be used.
workdir_parent:
# Volumes (including bind mounts) can be mounted to containers. Glob syntax is supported, see https://github.com/gobwas/glob
# You can specify multiple volumes. If the sequence is empty, no volumes can be mounted.
# For example, if you only allow containers to mount the `data` volume and all the JSON files in `/src`, you should change the config to:
# valid_volumes:
# - data
# - /etc/ssl/certs
# If you want to allow any volume, please use the following configuration:
# valid_volumes:
# - '**'
valid_volumes:
- /certs/client
# Overrides the docker host set by the DOCKER_HOST environment variable, and mounts on the job container.
# If "-" or "", no docker host will be mounted in the job container
# If "automount", an available docker host will automatically be found and mounted in the job container (e.g., /var/run/docker.sock).
# If it's a url, the specified docker host will be mounted in the job container
# Example urls: unix:///run/docker.socket or ssh://user@host
# The specified socket is mounted within the job container at /var/run/docker.sock
docker_host: "-"
# Pull docker image(s) even if already present
force_pull: false
# Rebuild local docker image(s) even if already present
force_rebuild: false
host:
# The parent directory of a job's working directory.
# If it's empty, $HOME/.cache/act/ will be used.
workdir_parent:
server:
# A map of connections to one or more Forgejo instances. Example:
#
# ```
# connections:
# example:
# url: https://example.com/
# uuid: c9e50be9-a7c3-4aee-ba35-624c4ff8c519
# token: 6634bb58be0db23cc013a2e72dd1828ae0257cf
# fetch_interval: 30s
# codeberg:
# url: https://codeberg.org/
# uuid: f543b661-cb02-4ba2-9820-108df62808b5
# token_url: file:$CREDENTIALS_DIRECTORY/token.txt
# labels:
# - debian:docker://docker.io/library/node:lts-trixie
# ```
#
# The map's keys (`example`, and `codeberg` above) serve as the connections'
# names.
#
# The runner token can either be specified inline using `token` or be loaded
# from a file using `token_url`. The methods are mutually exclusive.
# `token_url` supports a single placeholder: `$CREDENTIALS_DIRECTORY`. If the
# environment variable `CREDENTIALS_DIRECTORY` exists, the placeholder is
# replaced with the value of `CREDENTIALS_DIRECTORY`. Otherwise, it is
# retained.
#
# Labels defined on a connection are limited to that particular connection.
# If a connection defines no labels, the labels declared by `runner.labels`
# are used instead.
#
# `fetch_interval` specifies how often Forgejo Runner should ask Forgejo for
# pending jobs. If `fetch_interval` is not defined on a connection,
# `runner.fetch_interval` is used. Note that Forgejo Runner might enforce a
# minimum value for certain instances like Codeberg.
connections:
default:
url: http://forgejo-server:3000
uuid: ${FORGEJO_RUNNER_UUID}
token: ${FORGEJO_RUNNER_TOKEN}
Turning Actions on
Nothing to switch on for Forgejo 16, the version on this page. The administrator guide: "As of Forgejo v1.21, Actions is enabled by default. It can be disabled by adding the following to app.ini", that is [actions] ENABLED = false. For each repository, the quick start says to check Settings > Units > Overview, where the Actions box must be ticked. The cheat sheet's default DEFAULT_REPO_UNITS includes repo.actions, so new repositories have it; DEFAULT_FORK_REPO_UNITS (repo.code,repo.pulls) and DEFAULT_MIRROR_REPO_UNITS do not, so forks and mirrors need the box ticked by hand. Source: Forgejo docs: Forgejo Actions administrator guide (Forgejo Runner, Enabling/Disabling; runner-installation/ redirects here) checked 2026-10-01; Forgejo docs: Actions quick start (Units > Overview, first workflow) checked 2026-10-01; Forgejo docs: Configuration Cheat Sheet (DEFAULT_REPO_UNITS, DEFAULT_FORK_REPO_UNITS) checked 2026-10-01
Security, in Forgejo's words
Forgejo Runner performs remote code execution. That poses significant security threats for the host and network that it operates upon.
Source: Forgejo docs: Forgejo Actions administrator guide (Forgejo Runner, Enabling/Disabling; runner-installation/ redirects here) checked 2026-10-01For Forgejo Actions, their entire purpose is to perform remote code execution.
Source: Forgejo docs: Securing Forgejo Actions Deployments checked 2026-10-01- On giving jobs the Docker socket (docker_host: automount, or mounting /var/run/docker.sock), which this file does not do:
assuming that both Forgejo and Forgejo Runner are using the same Docker daemon, granting direct access to that daemon would allow an executed Action to shut down the Forgejo instance (see diagram below), or perform far more dangerous actions like creating an administrator account with unlimited access to the instance.
For automount the page adds: "This configuration is only advisable if measures are taken to ensure that only trusted users are able to access the Forgejo instance." Source: Forgejo docs: Utilizing Docker within Actions (Docker-in-Docker, automount) checked 2026-10-01 - On Docker-in-Docker, which this file uses:
This configuration prevents access to the host's Docker resources, as they are not available within the job container
Its administrator notes add that with runner.capacity above 1 (it is 1 here) "job containers will be able to view and interact with each other through the docker CLI", and that images and containers a job leaves in the Docker-in-Docker daemon can be inspected by any later job on the same runner. Source: Forgejo docs: Utilizing Docker within Actions (Docker-in-Docker, automount) checked 2026-10-01 - On the network setting the example chooses:
Changing the network mode to "host" will remove restrictions to allow all containers to communicate freely with each other and the host, without any job isolation.
Here that host is the Docker-in-Docker container, which shares forgejo-actions with Forgejo, so a job can reach forgejo-server:3000 directly. Source: Forgejo docs: Securing Forgejo Actions Deployments checked 2026-10-01 - On pull requests from forks:
their first pull request to the repository will require review from a contributor and approval before workflows can execute. After that, any future pull request that Mallory makes will have the workflow executed, including any modifications made in the fork.
Source: Forgejo docs: Securing Forgejo Actions Deployments checked 2026-10-01
Where the docs are silent: Forgejo's pages do not call any runner setup safe for untrusted repositories, and they do not say how well the privileged Docker-in-Docker container (privileged: true in both of Forgejo's compose examples) is isolated from the server it runs on. Source: Forgejo docs: Securing Forgejo Actions Deployments checked 2026-10-01; Forgejo docs: Utilizing Docker within Actions (Docker-in-Docker, automount) checked 2026-10-01; Forgejo docs: Forgejo Runner, Installation with Docker (OCI image, docker-compose.yml) checked 2026-10-01
What this cannot do: it does not size runners (the runner pages read for this section give no CPU, RAM or disk figure) or set up runners on other machines.
Sources
Every page below was fetched on the date shown.
- forgejo.org front page checked 2026-09-23 (what it does, what it replaces)
- forgejo.org front page (Lightweight and performant) checked 2026-09-23 (hardware requirements)
- Forgejo docs: Installation with Docker (docker-compose example, FORGEJO__section__KEY variables) checked 2026-09-23 (compose definition and proxy settings, PostgreSQL version, Git over SSH)
- Forgejo docs: Reverse proxy (Caddy HTTPS example) checked 2026-09-23 (compose definition and proxy settings, PostgreSQL version)
- Forgejo docs: Configuration Cheat Sheet (ROOT_URL, DISABLE_SSH) checked 2026-09-23 (compose definition and proxy settings, PostgreSQL version, Run Forgejo Actions (CI), Git over SSH)
- Caddy docs: Keep Caddy running (Docker Compose section) checked 2026-09-23 (Caddy)
- Vaultwarden wiki: Caddy with HTTP challenge (uses the caddy:2 image) checked 2026-09-23 (Caddy)
- Forgejo docs: Upgrade guide (Backup, Verify Forgejo works) checked 2026-09-24 (backup plan, update notes, PostgreSQL backup plan, PostgreSQL update notes)
- Forgejo docs: Command-line interface (dump) checked 2026-09-24 (backup plan)
- Caddy docs: Conventions, Data directory checked 2026-09-24 (backup plan)
- Docker docs: Volumes, Back up, restore, or migrate data volumes checked 2026-09-24 (backup plan)
- Docker docs: docker compose pull checked 2026-09-30 (update steps)
- Docker docs: docker compose up (recreates changed containers, keeps volumes) checked 2026-09-30 (update steps)
- Docker docs: docker image prune checked 2026-09-30 (update steps)
- Forgejo docs: Database Preparation (PostgreSQL >= 14) checked 2026-09-30 (PostgreSQL version)
- Docker Official Image postgres: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, PGDATA (changed in 18) checked 2026-09-30 (PostgreSQL version)
- PostgreSQL: Versioning Policy (final release date of each major version) checked 2026-09-30 (PostgreSQL version, PostgreSQL update notes)
- PostgreSQL docs: pg_dump checked 2026-09-30 (PostgreSQL backup plan)
- PostgreSQL docs: Upgrading a PostgreSQL Cluster checked 2026-09-30 (PostgreSQL update notes, database upgrade)
- Forgejo docs: Forgejo Actions administrator guide (Forgejo Runner, Enabling/Disabling; runner-installation/ redirects here) checked 2026-10-01 (Run Forgejo Actions (CI))
- Forgejo docs: Forgejo Runner, Installation with Docker (OCI image, docker-compose.yml) checked 2026-10-01 (Run Forgejo Actions (CI))
- Forgejo docs: Forgejo Runner Registration (interactive registration) checked 2026-10-01 (Run Forgejo Actions (CI))
- Forgejo docs: Forgejo Runner Configuration (labels, configuration file reference) checked 2026-10-01 (Run Forgejo Actions (CI))
- Forgejo docs: Securing Forgejo Actions Deployments checked 2026-10-01 (Run Forgejo Actions (CI))
- Forgejo docs: Utilizing Docker within Actions (Docker-in-Docker, automount) checked 2026-10-01 (Run Forgejo Actions (CI))
- forgejo/runner repository: examples/docker-compose (compose-forgejo-and-runner.yml, compose-demo-workflow.yml, README) checked 2026-10-01 (Run Forgejo Actions (CI))
- forgejo/runner v13.2.0: config.example.yaml, the file forgejo-runner generate-config prints checked 2026-10-01 (Run Forgejo Actions (CI))
- Forgejo docs: Actions quick start (Units > Overview, first workflow) checked 2026-10-01 (Run Forgejo Actions (CI))
- Docker docs: Merge Compose files (compose.override.yaml is read by default) checked 2026-10-01 (Run Forgejo Actions (CI))
- compose-go (the loader docker compose uses): DefaultFileNames and DefaultOverrideFileNames checked 2026-10-01 (Run Forgejo Actions (CI))
- Forgejo docs: Recommended Settings and Tips (OpenSSH recommendations) checked 2026-10-09 (Git over SSH)
- Forgejo docs: Your First Repository checked 2026-10-09 (Git over SSH)
- Forgejo v16.0.5: docker/root/etc/s6/openssh/setup (the image's sshd start script) checked 2026-10-09 (Git over SSH)
- Forgejo v16.0.5: docker/root/etc/templates/sshd_config checked 2026-10-09 (Git over SSH)
- Codeberg docs: Adding an SSH key to your account (Codeberg runs Forgejo) checked 2026-10-09 (Git over SSH)
- Docker docs: Packet filtering and firewalls, Docker and ufw checked 2026-10-09 (Git over SSH)