mes_skills/docs/tuto-gitea.md

# 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 |