| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .env.example | ||
| .gitignore | ||
| docker-compose.yml | ||
| README.md | ||
Forgejo + Forgejo Runner sur un VPS (Docker Compose)
Ce dépôt permet d'installer sur un VPS :
- Forgejo (forge Git auto-hébergée) avec une base PostgreSQL ;
- un Forgejo Runner (pour exécuter les workflows Forgejo Actions), qui lance ses jobs dans un conteneur Docker-in-Docker isolé.
Ce guide décrit une installation sans reverse proxy : Forgejo est exposé directement sur le port 3000 du VPS.
Arborescence
forgejo/
├── docker-compose.yml
├── .env.example # modèle des variables d'environnement
├── .env # tes variables (à créer, ne pas versionner)
├── data/ # données Forgejo (dépôts, app.ini, clés SSH…) → /data dans le conteneur
└── runner_data/ # données du runner → /data dans le conteneur runner
├── runner-config.yml # configuration du runner (générée à l'étape 7)
└── .runner # identifiants d'enregistrement du runner (générés à l'étape 8)
Ports utilisés
| Port hôte | Service | Rôle |
|---|---|---|
3000 |
forgejo | Interface web + clonage HTTP |
2245 |
forgejo | Clonage / push en SSH (le port 22 reste au sshd du VPS) |
Prérequis
-
Un VPS Linux (Debian/Ubuntu) avec un accès
sudo. -
Docker Engine et le plugin Docker Compose :
curl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker $USER # puis se déconnecter / reconnecter docker compose version -
Un serveur PostgreSQL accessible depuis le conteneur Forgejo (voir étape 3).
-
Optionnel : un nom de domaine (ex.
git.mondomaine.fr) qui pointe vers l'IP du VPS. Sinon, l'IP publique du VPS suffit.
1. Récupérer les fichiers sur le VPS
# depuis ta machine
scp -r forgejo/ user@IP_DU_VPS:~/
# puis sur le VPS
cd ~/forgejo
mkdir -p data runner_data
2. Adapter docker-compose.yml (sans reverse proxy)
Le docker-compose.yml du dépôt est prévu pour Traefik. Pour une installation sans reverse proxy, modifie le service forgejo :
- Supprime le bloc
networks:du serviceforgejoet le blocnetworks:de fin de fichier (le réseautraefikn'existe pas sur ton VPS). - Supprime tout le bloc
labels:(labels Traefik / Dozzle). - Expose le port web
3000. - Passe
ROOT_URLen HTTP sur le port 3000 (il n'y a plus de proxy pour gérer le HTTPS).
Le service forgejo doit ressembler à ceci :
services:
forgejo:
image: codeberg.org/forgejo/forgejo:16
container_name: forgejo
restart: unless-stopped
environment:
- USER_UID=1000
- USER_GID=1000
- FORGEJO__server__DOMAIN=${DOMAIN_URL}
- FORGEJO__server__ROOT_URL=http://${DOMAIN_URL}:3000/
- FORGEJO__server__SSH_DOMAIN=${DOMAIN_URL}
- FORGEJO__server__SSH_PORT=2245
- FORGEJO__database__DB_TYPE=postgres
- FORGEJO__database__HOST=${FORGEJO_DB_HOST}
- FORGEJO__database__NAME=${FORGEJO_DB_NAME}
- FORGEJO__database__USER=${FORGEJO_DB_USER}
- FORGEJO__database__PASSWD=${FORGEJO_DB_PASS}
- FORGEJO__service__DISABLE_REGISTRATION=true
- FORGEJO__actions__ENABLED=true
volumes:
- ./data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000" # interface web
- "2245:22" # SSH git → port hôte 2245 (le 22 est pris par le sshd du VPS)
Les services runner et docker-in-docker restent inchangés.
⚠️ Sans reverse proxy, le trafic web n'est pas chiffré (HTTP). Évite de te connecter depuis des réseaux non fiables, ou ajoute un reverse proxy plus tard.
3. Base de données PostgreSQL
Forgejo a besoin d'une base PostgreSQL. Deux options :
Option A — PostgreSQL déjà installé ailleurs
Crée un utilisateur et une base dédiés :
CREATE ROLE forgejo WITH LOGIN PASSWORD 'un_mot_de_passe_solide';
CREATE DATABASE forgejodb WITH OWNER forgejo TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
FORGEJO_DB_HOST doit être joignable depuis le conteneur (format hôte:port, ex. 10.0.0.5:5432). Attention : localhost désigne le conteneur lui-même, pas le VPS.
Option B — PostgreSQL dans le même docker-compose.yml
Ajoute ce service dans docker-compose.yml :
db:
image: postgres:17
container_name: forgejo_db
restart: unless-stopped
environment:
- POSTGRES_DB=${FORGEJO_DB_NAME}
- POSTGRES_USER=${FORGEJO_DB_USER}
- POSTGRES_PASSWORD=${FORGEJO_DB_PASS}
volumes:
- ./postgres:/var/lib/postgresql/data
Ajoute aussi depends_on: [db] au service forgejo, et mets FORGEJO_DB_HOST=db:5432 dans le .env.
4. Variables d'environnement
cp .env.example .env
nano .env
Exemple :
FORGEJO_DB_NAME=forgejodb
FORGEJO_DB_PASS=un_mot_de_passe_solide
FORGEJO_DB_USER=forgejo
FORGEJO_DB_HOST=db:5432
DOMAIN_URL=git.mondomaine.fr # ou l'IP du VPS, sans http(s):// ni port
5. Permissions des dossiers et pare-feu
Le conteneur Forgejo tourne avec l'UID/GID 1000, et le runner avec 1001 (cf. user: 1001:1001 dans le compose) :
sudo chown -R 1000:1000 data
sudo chown -R 1001:1001 runner_data
Si un pare-feu est actif (ex. ufw), ouvre les ports :
sudo ufw allow 3000/tcp
sudo ufw allow 2245/tcp
Pense aussi au pare-feu de ton hébergeur (console OVH, Hetzner, Scaleway…) s'il y en a un.
6. Démarrer Forgejo et créer le compte administrateur
On démarre d'abord uniquement Forgejo (le runner ne peut pas démarrer tant qu'il n'est ni configuré ni enregistré) :
docker compose up -d forgejo # ajoute "db" si tu as choisi l'option B
docker compose logs -f forgejo
Ouvre ensuite http://DOMAIN_URL:3000 dans ton navigateur. La page d'installation s'affiche avec les paramètres déjà remplis via les variables d'environnement :
- Vérifie les paramètres de la base de données et du serveur.
- Déplie « Paramètres du compte administrateur » et crée ton compte admin. C'est indispensable, car les inscriptions publiques sont désactivées (
DISABLE_REGISTRATION=true). - Clique sur Installer Forgejo.
7. Configurer le runner (runner_data/runner-config.yml)
Le runner est lancé avec forgejo-runner daemon --config runner-config.yml. Son répertoire de travail est /data, monté sur ./runner_data. Le fichier doit donc se trouver dans runner_data/runner-config.yml.
Générer la configuration par défaut :
docker compose run --rm --no-deps -T runner forgejo-runner generate-config > runner_data/runner-config.yml
sudo chown 1001:1001 runner_data/runner-config.yml
Puis édite runner_data/runner-config.yml et vérifie ou ajuste au minimum :
runner:
# fichier d'enregistrement, relatif à /data → runner_data/.runner
file: .runner
# nombre de jobs exécutés en parallèle
capacity: 1
container:
# Les conteneurs de jobs sont créés dans le Docker-in-Docker.
# "host" = ils partagent le réseau du conteneur docker_dind, ce qui leur
# permet de joindre Forgejo et les services du compose.
network: host
# Laisser vide : le runner utilise DOCKER_HOST=tcp://docker-in-docker:2375
# défini dans docker-compose.yml.
docker_host: ""
Les labels (images utilisées pour les jobs) sont définis à l'enregistrement (étape suivante). Si tu renseignes
runner.labelsdans ce fichier, ils remplacent ceux de l'enregistrement.
8. Enregistrer le runner auprès de Forgejo
-
Dans Forgejo : Administration du site → Actions → Runners → Créer un nouveau runner, puis copie le jeton d'enregistrement. (Tu peux aussi créer un runner limité à une organisation ou à un dépôt depuis leurs paramètres respectifs.)
-
Sur le VPS :
docker compose run --rm --no-deps runner forgejo-runner register --no-interactive \ --instance http://DOMAIN_URL:3000 \ --token LE_JETON_COPIÉ \ --name runner-vps \ --labels "docker:docker://node:lts-bookworm,ubuntu-latest:docker://node:lts-bookworm,alpine:docker://node:lts-alpine"Cela crée
runner_data/.runner. Garde ce fichier privé : il contient le secret du runner.Labels disponibles :
Label ( runs-on:)Image Usage docker,ubuntu-latestnode:lts-bookwormDebian + Node.js LTS : image par défaut, compatible avec la plupart des actions alpinenode:lts-alpineAlpine + Node.js LTS : image légère et rapide à télécharger Le tag
ltssuit toujours la version LTS active de Node.js. Pour figer une version, remplace-le par le numéro de la LTS (ex.node:24-bookworm,node:24-alpine).Sur l'image Alpine, Node.js est présent (les actions JavaScript comme
actions/checkoutfonctionnent), mais pasbashnigit. Le shell par défaut estsh; installe ce qu'il te faut avecapk add --no-cache bash git.
9. Démarrer toute la stack
docker compose up -d
docker compose ps
docker compose logs -f runner
Le runner doit apparaître comme en ligne dans Administration du site → Actions → Runners.
10. Tester avec un workflow
Dans un dépôt, active Actions si besoin (Paramètres → Unités → Actions), puis crée .forgejo/workflows/test.yml :
on: [push]
jobs:
test:
runs-on: docker
steps:
- uses: actions/checkout@v4
- run: echo "Hello depuis le runner Forgejo !" && node --version && ls -la
test-alpine:
runs-on: alpine
steps:
- run: apk add --no-cache git
- uses: actions/checkout@v4
- run: cat /etc/alpine-release && node --version
Pousse le fichier : le job apparaît dans l'onglet Actions du dépôt.
Utilisation de Git
-
HTTP :
git clone http://DOMAIN_URL:3000/utilisateur/depot.git -
SSH : ajoute ta clé publique dans Paramètres → Clés SSH / GPG, puis :
git clone ssh://git@DOMAIN_URL:2245/utilisateur/depot.git
Mise à jour
docker compose pull
docker compose up -d
Avant de changer de version majeure (ex.
forgejo:16→forgejo:17,runner:13→runner:14), lis les notes de version et fais une sauvegarde.
Sauvegarde
À sauvegarder régulièrement :
-
data/: dépôts, configurationapp.ini, pièces jointes, clés ; -
runner_data/:runner-config.ymlet.runner; -
la base PostgreSQL, par exemple avec l'option B :
docker exec forgejo_db pg_dump -U forgejo forgejodb > forgejo-$(date +%F).sql
Dépannage
| Symptôme | Piste |
|---|---|
Le conteneur runner redémarre en boucle |
runner_data/runner-config.yml ou runner_data/.runner est absent, ou appartient au mauvais utilisateur (sudo chown -R 1001:1001 runner_data). |
permission denied dans les logs Forgejo |
sudo chown -R 1000:1000 data |
| Forgejo n'arrive pas à joindre la base | Vérifie FORGEJO_DB_HOST : il doit être joignable depuis le conteneur (pas localhost). |
| Un job reste en attente | Le runs-on: du workflow doit correspondre à un label du runner (docker, ubuntu-latest ou alpine). |
actions/checkout échoue |
Vérifie que ROOT_URL (http://DOMAIN_URL:3000/) est joignable depuis le VPS lui-même et que le port 3000 est ouvert. |