docs: tutoriel Gitea — installation, SSH, API et usage avec mes_skills
This commit is contained in:
@@ -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 |
|
||||
Reference in New Issue
Block a user