From 461d66a90fcc735db2d9d30c496f0c0782cbd795 Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Mon, 27 Apr 2026 19:54:44 +0200 Subject: [PATCH] docs: add Gitea installation guide for Debian 11 with ISPConfig --- docs/GITEA_INSTALL.md | 322 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 docs/GITEA_INSTALL.md diff --git a/docs/GITEA_INSTALL.md b/docs/GITEA_INSTALL.md new file mode 100644 index 0000000..17dbd9e --- /dev/null +++ b/docs/GITEA_INSTALL.md @@ -0,0 +1,322 @@ +# Installation de Gitea sur Debian 11 avec Apache/ISPConfig + +Gitea sera accessible sur `https://git.unespace.com` en reverse proxy devant Apache. +Les repos existants dans `/opt/git/` seront migrés à la fin. + +--- + +## Table des matières + +1. [Prérequis Apache](#1-prérequis-apache) +2. [Créer l'utilisateur système Gitea](#2-créer-lutilisateur-système-gitea) +3. [Télécharger et installer le binaire](#3-télécharger-et-installer-le-binaire) +4. [Créer les répertoires et la configuration](#4-créer-les-répertoires-et-la-configuration) +5. [Créer le service systemd](#5-créer-le-service-systemd) +6. [Démarrer Gitea et finaliser l'installation](#6-démarrer-gitea-et-finaliser-linstallation) +7. [Configurer le VHost dans ISPConfig](#7-configurer-le-vhost-dans-ispconfig) +8. [Migrer les repos existants](#8-migrer-les-repos-existants) +9. [Mettre à jour les remotes locaux](#9-mettre-à-jour-les-remotes-locaux) + +--- + +## 1. Prérequis Apache + +Activer les modules proxy si ce n'est pas déjà fait : + +```bash +a2enmod proxy proxy_http headers +systemctl reload apache2 +``` + +--- + +## 2. Créer l'utilisateur système Gitea + +Gitea a besoin de son propre utilisateur Unix. On le crée **sans home** et **sans shell** pour limiter la surface d'attaque, mais on lui donne accès au répertoire des repos existants : + +```bash +adduser --system --shell /bin/bash --gecos 'Gitea' --group --home /opt/gitea gitea +``` + +Pour que Gitea puisse lire les repos appartenant à l'utilisateur `git`, on ajoute `gitea` au groupe `git` : + +```bash +usermod -aG git gitea +``` + +> Si tes repos dans `/opt/git/` appartiennent à `git:git`, cette étape est nécessaire pour la migration. + +--- + +## 3. Télécharger et installer le binaire + +Récupérer la dernière version stable depuis la page des releases Gitea. À adapter avec le numéro de version actuel : + +```bash +# Vérifier la dernière version sur https://github.com/go-gitea/gitea/releases +GITEA_VERSION="1.22.3" + +wget -O /tmp/gitea https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64 +chmod +x /tmp/gitea +mv /tmp/gitea /usr/local/bin/gitea + +# Vérifier +gitea --version +``` + +--- + +## 4. Créer les répertoires et la configuration + +```bash +# Répertoires de données +mkdir -p /opt/gitea/{custom,data,log,repositories} +chown -R gitea:gitea /opt/gitea +chmod -R 750 /opt/gitea + +# Répertoire de configuration +mkdir -p /etc/gitea +chown root:gitea /etc/gitea +chmod 770 /etc/gitea +``` + +Créer le fichier de configuration `/etc/gitea/app.ini` : + +```bash +cat > /etc/gitea/app.ini << 'EOF' +APP_NAME = Adastra Git +RUN_USER = gitea +RUN_MODE = prod +WORK_PATH = /opt/gitea + +[server] +PROTOCOL = http +HTTP_ADDR = 127.0.0.1 +HTTP_PORT = 3030 +DOMAIN = git.unespace.com +ROOT_URL = https://git.unespace.com/ +DISABLE_SSH = false +SSH_PORT = 22 +SSH_DOMAIN = git.unespace.com +START_SSH_SERVER = false + +[database] +DB_TYPE = sqlite3 +PATH = /opt/gitea/data/gitea.db + +[repository] +ROOT = /opt/gitea/repositories + +[security] +INSTALL_LOCK = false +SECRET_KEY = +INTERNAL_TOKEN = + +[log] +ROOT_PATH = /opt/gitea/log +MODE = file +LEVEL = warn + +[service] +DISABLE_REGISTRATION = false +REQUIRE_SIGNIN_VIEW = false +EOF + +chown root:gitea /etc/gitea/app.ini +chmod 660 /etc/gitea/app.ini +``` + +> **Note :** `INSTALL_LOCK = false` permet à l'installeur web de fonctionner au premier démarrage. Il passera à `true` automatiquement après. +> Le port `3030` est choisi pour éviter tout conflit avec l'API Node.js (3200) et d'autres services éventuels. + +--- + +## 5. Créer le service systemd + +```bash +cat > /etc/systemd/system/gitea.service << 'EOF' +[Unit] +Description=Gitea (Git with a cup of tea) +After=network.target + +[Service] +Type=simple +User=gitea +Group=gitea +WorkingDirectory=/opt/gitea +ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini +Restart=always +RestartSec=2s +Environment=USER=gitea HOME=/opt/gitea GITEA_WORK_DIR=/opt/gitea + +[Install] +WantedBy=multi-user.target +EOF + +systemctl daemon-reload +systemctl enable gitea +systemctl start gitea +systemctl status gitea +``` + +Vérifier que Gitea écoute bien sur le bon port : + +```bash +ss -tlnp | grep 3030 +``` + +--- + +## 6. Démarrer Gitea et finaliser l'installation + +À ce stade Gitea tourne mais l'interface d'installation web n'est pas encore accessible publiquement (le VHost n'est pas créé). On peut tester depuis le serveur lui-même : + +```bash +curl -s http://127.0.0.1:3030 | head -5 +# doit retourner du HTML +``` + +L'installation web sera finalisée **après** la configuration du VHost (étape 7). + +--- + +## 7. Configurer le VHost dans ISPConfig + +### 7.1 Créer le site web + +Dans ISPConfig → **Sites → Ajouter un site web** : + +| Champ | Valeur | +|---|---| +| Domain | `git.unespace.com` | +| Document Root | `/var/www/gitea-placeholder` (peu importe, ne sera pas utilisé) | +| Auto-subdomain | Aucun | +| Redirect type | Laisser vide | + +Sauvegarder. + +### 7.2 Activer le SSL Let's Encrypt + +Dans l'onglet **SSL** du site que tu viens de créer : + +- Cocher **SSL** +- Cocher **Let's Encrypt** +- Sauvegarder + +ISPConfig demande le certificat automatiquement. Attendre que le statut passe à "actif" (peut prendre 1-2 minutes). + +### 7.3 Ajouter les directives reverse proxy + +Dans l'onglet **Options** (ou **Directives Apache** selon ta version d'ISPConfig), dans le champ **Apache Directives**, coller : + +```apache +ProxyPreserveHost On +ProxyPass / http://127.0.0.1:3030/ +ProxyPassReverse / http://127.0.0.1:3030/ +RequestHeader set X-Forwarded-Proto "https" +RequestHeader set X-Real-IP %{REMOTE_ADDR}s +``` + +Répéter l'opération dans le champ **Apache Directives SSL** (le champ équivalent pour le VHost HTTPS) avec les mêmes lignes. + +Sauvegarder. ISPConfig recharge Apache automatiquement. + +### 7.4 Vérifier + +```bash +curl -I https://git.unespace.com +# HTTP/2 200 ou redirection vers l'installeur Gitea +``` + +### 7.5 Finaliser l'installation Gitea via le navigateur + +Ouvre `https://git.unespace.com` dans ton navigateur. L'installeur Gitea s'affiche. + +Paramètres recommandés : + +| Champ | Valeur | +|---|---| +| Base URL | `https://git.unespace.com/` | +| SSH Server Domain | `git.unespace.com` | +| SSH Port | `22` | +| HTTP Port | `3030` | +| Database | SQLite3 (déjà configuré) | +| Compte administrateur | Remplir nom/email/mot de passe | + +Cliquer **Installer Gitea**. L'installeur met à jour `app.ini` et redirige vers la page d'accueil. + +--- + +## 8. Migrer les repos existants + +Tes repos actuels sont dans `/opt/git/` sous forme de repos bare (ex. `/opt/git/adastra_api.git`). + +### Option A — Via l'interface Gitea (recommandé) + +Pour chaque repo : + +1. Dans Gitea, créer un nouveau dépôt vide (même nom, sans initialisation) +2. Depuis ta machine locale, ajouter le nouveau remote et pousser : + +```bash +cd /chemin/local/adastra_api +git remote add gitea git@git.unespace.com:TON_USERNAME/adastra_api.git +git push gitea --all +git push gitea --tags +``` + +### Option B — Copie directe côté serveur + +Si tu veux éviter de tout repousser depuis le local, tu peux cloner les repos bare existants directement dans le répertoire de Gitea : + +```bash +# Pour chaque repo — adapter le nom d'utilisateur Gitea +su - gitea -s /bin/bash + +cd /opt/gitea/repositories/TON_USERNAME/ + +# Clone bare du repo existant +git clone --mirror /opt/git/adastra_api.git adastra_api.git +git clone --mirror /opt/git/adastra_app.git adastra_app.git +``` + +Puis dans Gitea → Admin panel → **Git Repositories** → **Git Resync** pour que Gitea indexe les repos copiés. + +--- + +## 9. Mettre à jour les remotes locaux + +Une fois les repos migrés, mettre à jour les remotes dans tes clones locaux : + +```bash +# Vérifier les remotes actuels +git remote -v + +# Remplacer l'ancien remote origin +git remote set-url origin git@git.unespace.com:TON_USERNAME/adastra_api.git +git remote set-url origin git@git.unespace.com:TON_USERNAME/adastra_app.git + +# Vérifier +git remote -v +git fetch origin +``` + +> L'ancien serveur Git continue de fonctionner en parallèle jusqu'à ce que tu sois certain que tout est migré. + +--- + +## Commandes d'administration utiles + +```bash +# Statut du service +systemctl status gitea + +# Logs en temps réel +journalctl -u gitea -f + +# Mise à jour de Gitea (remplacer le binaire puis redémarrer) +systemctl stop gitea +wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/NEW_VERSION/gitea-NEW_VERSION-linux-amd64 +chmod +x /usr/local/bin/gitea +systemctl start gitea +```