sdk_client/docs/SSH_USAGE.md

# Documentation SSH complète - ihm_client

## Vue d'ensemble

Ce document consolide toute la documentation SSH pour le projet `ihm_client`, couvrant l'automatisation des push, la configuration CI/CD, et les bonnes pratiques de sécurité.

## Table des matières

- [Configuration automatique](#configuration-automatique)
- [Scripts d'automatisation](#scripts-dautomatisation)
- [Workflow CI/CD](#workflow-cicd)
- [Alias Git](#alias-git)
- [Bonnes pratiques](#bonnes-pratiques)
- [Dépannage](#dépannage)

---

## Configuration automatique

### Configuration Git globale

La configuration SSH est automatiquement appliquée pour tous les push :

```bash
git config --global url."git@git.4nkweb.com:".insteadOf "https://git.4nkweb.com/"
```

### Vérification SSH

Test automatique de la connexion SSH :

```bash
ssh -T git@git.4nkweb.com
```

---

## Scripts d'automatisation

### 1. Script principal : `auto-ssh-push.sh`

Le script `scripts/auto-ssh-push.sh` offre plusieurs modes de push automatique :

#### Options disponibles

```bash
# Push rapide (message automatique)
./scripts/auto-ssh-push.sh quick

# Push avec message personnalisé
./scripts/auto-ssh-push.sh message "feat: nouvelle fonctionnalité"

# Push sur une branche spécifique
./scripts/auto-ssh-push.sh branch feature/nouvelle-fonctionnalite

# Push et merge (avec confirmation)
./scripts/auto-ssh-push.sh merge

# Vérification du statut
./scripts/auto-ssh-push.sh status
```

#### Fonctionnalités

- **Configuration SSH automatique** - Plus besoin de configurer SSH manuellement
- **Push automatique** - Ajout, commit et push en une commande
- **Gestion des branches** - Support des branches personnalisées
- **Vérification SSH** - Test automatique de la connexion SSH
- **Messages de commit** - Messages automatiques ou personnalisés

### 2. Script d'initialisation : `init-ssh-env.sh`

Le script `scripts/init-ssh-env.sh` configure automatiquement l'environnement SSH :

```bash
./scripts/init-ssh-env.sh
```

#### Fonctionnalités

- Vérification de l'environnement de développement
- Configuration SSH automatique
- Test de connectivité SSH
- Configuration des alias Git
- Validation de la configuration

### 3. Script CI/CD : `setup-ssh-ci.sh`

Le script `scripts/setup-ssh-ci.sh` configure SSH pour les environnements CI/CD :

```bash
./scripts/setup-ssh-ci.sh
```

#### Fonctionnalités

- Détection automatique de l'environnement CI
- Configuration SSH pour Gitea Actions
- Gestion des clés SSH privées
- Test de connexion SSH
- Configuration Git pour SSH

---

## Workflow CI/CD

### Configuration Gitea Actions

Le workflow CI/CD dans `.gitea/workflows/ci.yml` inclut une étape de configuration SSH :

```yaml
- name: Setup SSH for Gitea
  run: |
    mkdir -p ~/.ssh
    echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
    chmod 600 ~/.ssh/id_rsa
    ssh-keyscan -H git.4nkweb.com >> ~/.ssh/known_hosts
    git config --global url."git@git.4nkweb.com:".insteadOf "https://git.4nkweb.com/"
```

### Variables d'environnement requises

- `SSH_PRIVATE_KEY` : Clé SSH privée pour l'authentification
- `SSH_PUBLIC_KEY` : Clé SSH publique (optionnelle)

### Jobs configurés

- **test** : Tests unitaires et d'intégration
- **security** : Tests de sécurité et audit
- **integration-test** : Tests d'intégration complets

---

## Alias Git

### Alias configurés

```bash
# Push rapide avec message automatique
git quick-push

# Push avec message personnalisé
git ssh-push "Mon message de commit"
```

### Configuration des alias

```bash
# Alias pour push rapide
git config --global alias.quick-push '!f() { git add . && git commit -m "Update $(date)" && git push origin $(git branch --show-current); }; f'

# Alias pour push avec message
git config --global alias.ssh-push '!f() { git add . && git commit -m "${1:-Auto-commit $(date)}" && git push origin $(git branch --show-current); }; f'
```

---

## Bonnes pratiques

### Sécurité

1. **Permissions des clés SSH**
   ```bash
   chmod 600 ~/.ssh/id_rsa
   chmod 644 ~/.ssh/id_rsa.pub
   chmod 600 ~/.ssh/config
   ```

2. **Configuration SSH sécurisée**
   ```bash
   Host git.4nkweb.com
       HostName git.4nkweb.com
       User git
       IdentityFile ~/.ssh/id_rsa
       StrictHostKeyChecking no
       UserKnownHostsFile=/dev/null
   ```

3. **Gestion des secrets**
   - Ne jamais commiter de clés SSH dans le code
   - Utiliser les secrets Gitea pour les clés privées
   - Rotation régulière des clés SSH

### Workflow recommandé

1. **Initialisation**
   ```bash
   ./scripts/init-ssh-env.sh
   ```

2. **Développement quotidien**
   ```bash
   # Push rapide
   ./scripts/auto-ssh-push.sh quick

   # Ou avec alias Git
   git quick-push
   ```

3. **Push avec message**
   ```bash
   ./scripts/auto-ssh-push.sh message "feat: nouvelle fonctionnalité"
   ```

---

## Dépannage

### Problèmes courants

#### 1. Échec d'authentification SSH

```bash
# Vérifier la configuration SSH
ssh -T git@git.4nkweb.com

# Vérifier les permissions
ls -la ~/.ssh/

# Régénérer la clé SSH si nécessaire
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_4nk
```

#### 2. Configuration Git incorrecte

```bash
# Vérifier la configuration Git
git config --global --list | grep url

# Reconfigurer SSH
git config --global url."git@git.4nkweb.com:".insteadOf "https://git.4nkweb.com/"
```

#### 3. Problèmes CI/CD

```bash
# Vérifier les variables d'environnement
echo $SSH_PRIVATE_KEY

# Tester la configuration SSH
./scripts/setup-ssh-ci.sh
```

### Messages d'erreur courants

- **"Permission denied"** : Vérifier les permissions des clés SSH
- **"Host key verification failed"** : Ajouter l'hôte aux known_hosts
- **"Could not resolve hostname"** : Vérifier la connectivité réseau

### Logs et debugging

```bash
# Activer le debug SSH
ssh -vT git@git.4nkweb.com

# Vérifier les logs Git
GIT_SSH_COMMAND="ssh -v" git push origin main
```

---

## Intégration avec 4NK_node

### Configuration pour l'intégration

Le projet `ihm_client` est configuré pour s'intégrer dans l'infrastructure `4NK_node` :

1. **Script d'intégration** : `scripts/integrate-4nk-node.sh`
2. **Configuration Docker** : `Dockerfile.4nk-node`
3. **Configuration Nginx** : `nginx.4nk-node.conf`
4. **Script de démarrage** : `start-4nk-node.sh`

### Workflow d'intégration

```bash
# Intégrer ihm_client dans 4NK_node
./scripts/integrate-4nk-node.sh

# Vérifier l'intégration
docker-compose -f docker-compose.4nk-node.yml up -d
```

---

## Évolution future

### Améliorations prévues

1. **Support multi-environnements**
   - Configuration automatique pour différents environnements
   - Gestion des clés SSH multiples

2. **Intégration avancée**
   - Support des hooks Git
   - Intégration avec d'autres outils CI/CD

3. **Sécurité renforcée**
   - Support des clés SSH temporaires
   - Audit automatique des permissions

### Maintenance

- Vérification régulière de la configuration SSH
- Mise à jour des scripts d'automatisation
- Documentation des nouvelles fonctionnalités

---

## Conclusion

L'automatisation SSH pour `ihm_client` simplifie considérablement le workflow de développement en éliminant la nécessité de configurer manuellement SSH pour chaque opération Git. Les scripts et alias fournis offrent une interface simple et sécurisée pour tous les push vers le repository.

### Ressources

- [Documentation SSH officielle](https://git-scm.com/book/fr/v2/Git-sur-le-serveur-Génération-d-une-clé-SSH)
- [Guide Gitea SSH](https://docs.gitea.com/usage/ssh-setup)
- [Bonnes pratiques SSH](https://www.ssh.com/academy/ssh/key)

---

**Dernière mise à jour** : $(date '+%Y-%m-%d')
**Version** : 1.0.0