Mon environnement git auto hébergé
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-20 08:58:42 +02:00
.env.example config init 2026-10-20 08:50:07 +02:00
.gitignore retrait du ds_store 2026-10-20 08:53:20 +02:00
docker-compose.yml config init 2026-10-20 08:50:07 +02:00
README.md config init 2026-10-20 08:50:07 +02:00

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 :

  1. Supprime le bloc networks: du service forgejo et le bloc networks: de fin de fichier (le réseau traefik n'existe pas sur ton VPS).
  2. Supprime tout le bloc labels: (labels Traefik / Dozzle).
  3. Expose le port web 3000.
  4. Passe ROOT_URL en 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 :

  1. Vérifie les paramètres de la base de données et du serveur.
  2. 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).
  3. 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.labels dans ce fichier, ils remplacent ceux de l'enregistrement.

8. Enregistrer le runner auprès de Forgejo

  1. 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.)

  2. 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-latest node:lts-bookworm Debian + Node.js LTS : image par défaut, compatible avec la plupart des actions
    alpine node:lts-alpine Alpine + Node.js LTS : image légère et rapide à télécharger

    Le tag lts suit 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/checkout fonctionnent), mais pas bash ni git. Le shell par défaut est sh ; installe ce qu'il te faut avec apk 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, configuration app.ini, pièces jointes, clés ;

  • runner_data/ : runner-config.yml et .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.