# 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. Workflow git pas à pas — pour débutant

### Le cycle de travail en 4 étapes

```
Modifier des fichiers
        ↓
   git add        ← "je veux inclure ces fichiers dans mon enregistrement"
        ↓
   git commit     ← "j'enregistre une version avec un message"
        ↓
   git push       ← "j'envoie mon travail vers Gitea"
```

Et dans l'autre sens :

```
   git pull       ← "je récupère les modifications de Gitea vers ma machine"
        ↓
Modifier des fichiers
        ↓
   ...
```

---

### Étape 0 — Vérifier où on en est (toujours commencer par là)

```bash
git status
```

Ce que ça dit :
- **"nothing to commit"** → tout est propre, rien à faire
- **"Changes not staged"** → tu as modifié des fichiers mais pas encore fait `git add`
- **"Changes to be committed"** → tu as fait `git add`, prêt pour `git commit`
- **"Your branch is ahead of origin"** → tu as des commits locaux à `push`

> 💡 **Règle d'or :** lance `git status` avant de faire quoi que ce soit. C'est ton tableau de bord.

---

### Étape 1 — `git add` — Préparer les fichiers à enregistrer

`git add` ne sauvegarde rien encore. Il dit juste à git : *"ces fichiers feront partie de mon prochain enregistrement"*.

```bash
# Ajouter un fichier précis
git add skills/dev/debugging/claude-code.md

# Ajouter tous les fichiers modifiés d'un dossier
git add skills/dev/debugging/

# Ajouter tous les fichiers modifiés du projet (à utiliser avec précaution)
git add .
```

Après un `git add`, refais `git status` pour voir ce qui est "en attente de commit" (en vert).

---

### Étape 2 — `git commit` — Enregistrer une version

`git commit` crée un point de sauvegarde local avec un message qui explique **ce que tu as fait et pourquoi**.

```bash
git commit -m "feat: ajout skill debugging pour claude-code"
```

> 💡 Un bon message de commit répond à la question : *"Si je lis ça dans 6 mois, je comprends ce qui a changé ?"*

**Conventions de messages (optionnel mais utile) :**

| Préfixe | Usage |
|---------|-------|
| `feat:` | Nouveau skill, nouvelle fonctionnalité |
| `fix:` | Correction d'une erreur |
| `docs:` | Modification de documentation |
| `chore:` | Maintenance, nettoyage |

À ce stade, ton travail est **sauvegardé localement** mais **pas encore sur Gitea**.

---

### Étape 3 — `git push` — Envoyer vers Gitea

`git push` envoie tes commits locaux vers ton dépôt Gitea. C'est à ce moment que les autres (ou toi depuis une autre machine) peuvent voir ton travail.

```bash
# Premier push sur une nouvelle branche
git push -u origin main

# Tous les push suivants (plus court)
git push
```

Si ça demande un mot de passe → tu utilises HTTPS. Passe en SSH (voir section 3) pour ne plus jamais avoir à saisir de mot de passe.

---

### Étape 4 — `git pull` — Récupérer les modifications de Gitea

`git pull` télécharge les modifications faites sur Gitea (par toi depuis une autre machine, ou par quelqu'un d'autre) et les intègre à ta copie locale.

```bash
git pull
```

> 💡 **Bonne habitude :** fais toujours `git pull` avant de commencer à travailler, pour être sûr d'avoir la version la plus récente.

---

### Exemple complet — Ajouter un skill et le pousser

```bash
# 1. Récupérer les dernières modifications de Gitea
git pull

# 2. Vérifier l'état du dépôt
git status

# 3. Créer ton nouveau skill
cp templates/claude-code.md skills/jardinage/arrosage/claude-code.md
# Éditer le fichier avec ton éditeur...

# 4. Vérifier ce qui a changé
git status
# → "Untracked files: skills/jardinage/arrosage/claude-code.md"

# 5. Préparer le fichier pour l'enregistrement
git add skills/jardinage/arrosage/claude-code.md

# 6. Vérifier (optionnel mais recommandé)
git status
# → "Changes to be committed: new file: skills/jardinage/..."

# 7. Enregistrer la version avec un message
git commit -m "feat: ajout skill arrosage pour jardinage"

# 8. Envoyer vers Gitea
git push
```

Résultat : ton skill est visible sur `https://gitea.maison43.duckdns.org/gilles/mes_skills`

---

### Voir l'historique de tes commits

```bash
# Compact (une ligne par commit)
git log --oneline -10

# Avec dates et auteur
git log --oneline --graph -10
```

---

### Annuler des erreurs courantes

```bash
# J'ai fait git add par erreur sur un fichier → l'enlever de la sélection
git restore --staged fichier.md

# J'ai modifié un fichier et je veux revenir à la version du dernier commit
git restore fichier.md

# Je veux voir ce que j'ai modifié avant de committer
git diff

# Je veux voir ce qui est dans le "add" (staged)
git diff --staged
```

---

## 9. 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 restore 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 |