From ee809bb2e25f90c0eb3c08dcb81f0fc32d545a78 Mon Sep 17 00:00:00 2001 From: Gilles Soulier Date: Sat, 16 May 2026 04:30:25 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20tutoriel=20Gitea=20=E2=80=94=20installa?= =?UTF-8?q?tion,=20SSH,=20API=20et=20usage=20avec=20mes=5Fskills?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/tuto-gitea.md | 364 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 364 insertions(+) create mode 100644 docs/tuto-gitea.md diff --git a/docs/tuto-gitea.md b/docs/tuto-gitea.md new file mode 100644 index 0000000..8f528f2 --- /dev/null +++ b/docs/tuto-gitea.md @@ -0,0 +1,364 @@ +# Tutoriel Gitea — Installation, Configuration et Utilisation + +**Sources officielles :** +- [Documentation Gitea](https://docs.gitea.com) +- [Installation binaire Linux](https://docs.gitea.com/installation/install-from-binary) +- [Configuration SSH dans Gitea](https://www.techaddressed.com/tutorials/add-verify-ssh-keys-gitea/) +- [API Gitea](https://docs.gitea.com/development/api-usage) + +--- + +## 1. Installation sur Debian/Ubuntu + +### 1.1 Prérequis + +```bash +sudo apt update && sudo apt install -y git curl wget +``` + +### 1.2 Créer un utilisateur système dédié + +```bash +sudo adduser --system --shell /bin/bash --gecos 'Gitea' \ + --group --disabled-password --home /home/gitea gitea +``` + +### 1.3 Créer l'arborescence des dossiers + +```bash +sudo mkdir -p /var/lib/gitea/{custom,data,log} +sudo chown -R gitea:gitea /var/lib/gitea/ +sudo chmod -R 750 /var/lib/gitea/ +sudo mkdir -p /etc/gitea +sudo chown root:gitea /etc/gitea +sudo chmod 770 /etc/gitea +``` + +### 1.4 Télécharger Gitea + +Récupère la dernière version depuis [github.com/go-gitea/gitea/releases](https://github.com/go-gitea/gitea/releases) : + +```bash +# Remplace x.y.z par la version actuelle +GITEA_VERSION="1.22.0" +wget -O /tmp/gitea "https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64" +sudo mv /tmp/gitea /usr/local/bin/gitea +sudo chmod +x /usr/local/bin/gitea +gitea --version +``` + +### 1.5 Créer le service systemd + +```bash +sudo nano /etc/systemd/system/gitea.service +``` + +Contenu du fichier : + +```ini +[Unit] +Description=Gitea (Git with a cup of tea) +After=network.target +After=mysqld.service +Wants=mysqld.service + +[Service] +RestartSec=2s +Type=simple +User=gitea +Group=gitea +WorkingDirectory=/var/lib/gitea/ +ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini +Restart=always +Environment=USER=gitea HOME=/home/gitea GITEA_WORK_DIR=/var/lib/gitea + +[Install] +WantedBy=multi-user.target +``` + +Activer et démarrer : + +```bash +sudo systemctl daemon-reload +sudo systemctl enable --now gitea +sudo systemctl status gitea +``` + +--- + +## 2. Configuration initiale (interface web) + +Ouvre `http://ton-serveur:3000` dans un navigateur. + +### 2.1 Paramètres recommandés + +| Paramètre | Valeur recommandée | +|-----------|-------------------| +| Base de données | SQLite (simple) ou MariaDB (production) | +| Titre du site | `mes_skills` ou ton nom | +| URL de base | `https://gitea.maison43.duckdns.org` | +| Port SSH | `22` (ou `2222` si conflit) | +| Port HTTP | `3000` | +| Dossier des dépôts | `/var/lib/gitea/data/repositories` | + +### 2.2 Création du compte administrateur + +Remplis les champs "Compte administrateur" pendant l'installation. Ce compte aura tous les droits. + +--- + +## 3. Configuration SSH + +### 3.1 Générer une clé SSH sur ta machine locale (si pas déjà fait) + +```bash +ssh-keygen -t ed25519 -C "ton@email.com" +# Clé publique générée dans : ~/.ssh/id_ed25519.pub +``` + +### 3.2 Ajouter la clé dans Gitea + +1. Connecte-toi à Gitea +2. **Paramètres** (icône profil) → **Paramètres** → **Clés SSH / GPG** +3. Cliquer **Ajouter une clé** +4. Coller le contenu de `~/.ssh/id_ed25519.pub` + +### 3.3 Tester la connexion SSH + +```bash +ssh -T git@gitea.maison43.duckdns.org +# Réponse attendue : +# Hi gilles! You've successfully authenticated, but Gitea does not provide shell access. +``` + +### 3.4 Configurer `~/.ssh/config` (optionnel mais recommandé) + +``` +Host gitea.maison43.duckdns.org + HostName gitea.maison43.duckdns.org + User git + IdentityFile ~/.ssh/id_ed25519 + Port 22 +``` + +--- + +## 4. Créer et utiliser un dépôt + +### 4.1 Créer un dépôt via l'interface + +1. Cliquer **+** → **Nouveau dépôt** +2. Nom : `mes_skills` +3. Visibilité : Privé ou Public selon ton choix +4. Initialiser avec un README : optionnel +5. Valider + +### 4.2 Cloner un dépôt existant + +```bash +# Via SSH (recommandé) +git clone git@gitea.maison43.duckdns.org:gilles/mes_skills.git + +# Via HTTPS +git clone https://gitea.maison43.duckdns.org/gilles/mes_skills.git +``` + +### 4.3 Configurer le remote sur un dépôt local existant + +```bash +git remote add origin git@gitea.maison43.duckdns.org:gilles/mes_skills.git +git push -u origin main +``` + +### 4.4 Workflow git quotidien + +```bash +git add fichier.md +git commit -m "feat: ajout skill debugging" +git push + +# Récupérer les modifications distantes +git pull +``` + +--- + +## 5. Tokens d'accès API + +Utile pour les scripts bash, l'installeur de skills, ou l'automatisation. + +### 5.1 Créer un token + +1. **Paramètres** → **Applications** → **Générer un nouveau token** +2. Nom : `mes_skills_installer` +3. Durée : illimitée ou 1 an +4. Permissions : `Repository` → Read (pour lire) / Write (pour pousser) +5. **Copier le token immédiatement** — il ne sera plus affiché + +### 5.2 Utiliser le token dans un script bash + +```bash +GITEA_TOKEN="ton_token_ici" +GITEA_URL="https://gitea.maison43.duckdns.org" + +# Lister les dépôts +curl -s -H "Authorization: token $GITEA_TOKEN" \ + "${GITEA_URL}/api/v1/repos/search" | jq '.data[].name' + +# Créer un fichier dans un dépôt +curl -s -X POST \ + -H "Authorization: token $GITEA_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"message":"feat: nouveau skill","content":"'"$(base64 -w0 mon_fichier.md)"'"}' \ + "${GITEA_URL}/api/v1/repos/gilles/mes_skills/contents/skills/dev/mon-skill/claude-code.md" +``` + +### 5.3 Stocker le token de façon sécurisée + +```bash +# Dans ~/.config/mes_skills/config (permissions 600) +mkdir -p ~/.config/mes_skills +echo "GITEA_TOKEN=ton_token_ici" > ~/.config/mes_skills/config +chmod 600 ~/.config/mes_skills/config + +# Charger dans un script +source ~/.config/mes_skills/config +``` + +--- + +## 6. Accès depuis l'extérieur (DuckDNS + reverse proxy) + +### 6.1 DuckDNS (DNS dynamique) + +Ton instance est accessible via `gitea.maison43.duckdns.org`. + +Pour maintenir le DNS à jour (si IP dynamique) : + +```bash +# Cron toutes les 5 minutes +*/5 * * * * curl -s "https://www.duckdns.org/update?domains=maison43&token=TON_TOKEN_DUCKDNS&ip=" > /dev/null +``` + +### 6.2 Reverse proxy Nginx (HTTPS) + +```nginx +server { + listen 443 ssl; + server_name gitea.maison43.duckdns.org; + + ssl_certificate /etc/letsencrypt/live/gitea.maison43.duckdns.org/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/gitea.maison43.duckdns.org/privkey.pem; + + location / { + proxy_pass http://localhost:3000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + } +} +``` + +Certificat Let's Encrypt : + +```bash +sudo apt install certbot python3-certbot-nginx +sudo certbot --nginx -d gitea.maison43.duckdns.org +``` + +--- + +## 7. Utilisation avec `mes_skills` + +### 7.1 Pousser des skills vers Gitea + +```bash +cd ~/Documents/vscode/mes_skills/mes_skills + +# Ajouter un nouveau skill +cp templates/claude-code.md skills/dev/mon-nouveau-skill/claude-code.md +# Éditer le fichier... + +git add skills/dev/mon-nouveau-skill/ +git commit -m "feat: ajout skill mon-nouveau-skill" +git push +``` + +### 7.2 Installer les skills depuis Gitea + +```bash +# Installation standard (clone depuis Gitea) +curl -fsSL https://gitea.maison43.duckdns.org/gilles/mes_skills/raw/branch/main/install.sh | bash + +# Installation depuis le dépôt local (développement) +SKILLS_REPO=/chemin/local bash install.sh +``` + +### 7.3 URL utiles de ton instance + +| Usage | URL | +|-------|-----| +| Interface web | `https://gitea.maison43.duckdns.org` | +| Dépôt mes_skills | `https://gitea.maison43.duckdns.org/gilles/mes_skills` | +| install.sh brut | `https://gitea.maison43.duckdns.org/gilles/mes_skills/raw/branch/main/install.sh` | +| API | `https://gitea.maison43.duckdns.org/api/v1` | +| Swagger API | `https://gitea.maison43.duckdns.org/api/swagger` | + +--- + +## 8. Commandes git essentielles + +```bash +# Statut du dépôt +git status + +# Historique compact +git log --oneline -10 + +# Voir les modifications avant commit +git diff + +# Annuler les modifications d'un fichier (non commité) +git checkout -- fichier.md + +# Créer une branche +git checkout -b ma-branche + +# Revenir sur main +git checkout main + +# Fusionner une branche +git merge ma-branche + +# Voir les remotes +git remote -v +``` + +--- + +## 9. Mise à jour de Gitea + +```bash +sudo systemctl stop gitea + +# Télécharger la nouvelle version +wget -O /tmp/gitea "https://dl.gitea.com/gitea/NOUVELLE_VERSION/gitea-NOUVELLE_VERSION-linux-amd64" +sudo mv /tmp/gitea /usr/local/bin/gitea +sudo chmod +x /usr/local/bin/gitea + +sudo systemctl start gitea +gitea --version +``` + +--- + +## 10. Dépannage courant + +| Problème | Solution | +|----------|----------| +| Port 3000 inaccessible | `sudo ufw allow 3000` ou vérifier le firewall | +| Push SSH refusé | Vérifier la clé SSH dans Gitea, tester avec `ssh -T git@...` | +| `git push` demande mot de passe | Utiliser SSH au lieu de HTTPS, ou configurer un credential helper | +| Gitea ne démarre pas | `sudo journalctl -u gitea -n 50` pour voir les logs | +| Clone lent | Vérifier la connexion réseau, utiliser `--depth=1` pour les gros dépôts |