272 lines
7.9 KiB
Markdown
272 lines
7.9 KiB
Markdown
# ClonePack
|
|
|
|
ClonePack est un système de clonage et de gel d'artefacts. Il permet de synchroniser des dépôts externes, de les figer à un instant donné, et de les exposer localement via un miroir HTTP.
|
|
|
|
## Types d'artefacts supportés
|
|
|
|
- Enterprise Linux (RPM/YUM/DNF)
|
|
- Debian/Ubuntu (APT)
|
|
- Docker images — *à venir*
|
|
- Binaires — *à venir*
|
|
|
|
## Fonctionnalités
|
|
|
|
- Clonage de dépôts RPM et APT avec vérification SHA256
|
|
- Scan régulier des sources pour détecter les nouveaux paquets
|
|
- Validation manuelle ou automatique des mises à jour
|
|
- Blocklist permanente par paquet (toutes versions)
|
|
- Snapshots avec diff et rollback (RPM)
|
|
- Proxy miroir HTTP accessible par ID ou par nom de dépôt
|
|
|
|
---
|
|
|
|
## Compilation
|
|
|
|
**Prérequis** : Go 1.25+
|
|
|
|
```bash
|
|
make build # compile → bin/clonepack
|
|
make run # compile + démarre le serveur
|
|
make test # lance les tests
|
|
make vet # analyse statique
|
|
make clean # supprime bin/
|
|
```
|
|
|
|
Le binaire est généré dans `bin/clonepack`.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
ClonePack se configure via fichier YAML ou variables d'environnement (préfixe `CLONEPACK_`).
|
|
|
|
**Fichier de config (optionnel) :**
|
|
```yaml
|
|
server:
|
|
host: 0.0.0.0
|
|
port: 8080
|
|
|
|
db:
|
|
path: ./clonepack.db
|
|
|
|
data_dir: ./data
|
|
|
|
sync:
|
|
interval: 1h
|
|
```
|
|
|
|
**Variables d'environnement :**
|
|
```bash
|
|
CLONEPACK_SERVER_PORT=9090
|
|
CLONEPACK_DB_PATH=/var/lib/clonepack/clonepack.db
|
|
CLONEPACK_DATA_DIR=/var/lib/clonepack/data
|
|
CLONEPACK_SYNC_INTERVAL=30m
|
|
```
|
|
|
|
**Démarrer le serveur :**
|
|
```bash
|
|
./bin/clonepack serve
|
|
./bin/clonepack serve --config /etc/clonepack/config.yaml
|
|
```
|
|
|
|
Par défaut le serveur écoute sur `http://0.0.0.0:8080`.
|
|
|
|
---
|
|
|
|
## CLI
|
|
|
|
Toutes les commandes CLI appellent l'API REST. L'URL du serveur se configure avec `--api-url` (défaut : `http://localhost:8080`).
|
|
|
|
### Dépôts
|
|
|
|
```bash
|
|
# Créer un dépôt RPM (sync auto)
|
|
./bin/clonepack repo create \
|
|
--name rocky9-baseos \
|
|
--type rpm \
|
|
--source-url https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os
|
|
|
|
# Créer un dépôt APT
|
|
./bin/clonepack repo create \
|
|
--name debian-bookworm \
|
|
--type apt \
|
|
--source-url https://deb.debian.org/debian \
|
|
--suite bookworm \
|
|
--components main,contrib \
|
|
--arch amd64
|
|
|
|
# Créer avec validation manuelle
|
|
./bin/clonepack repo create \
|
|
--name debian-bookworm \
|
|
--type apt \
|
|
--source-url https://deb.debian.org/debian \
|
|
--suite bookworm \
|
|
--sync-mode manual
|
|
|
|
# Lister les dépôts
|
|
./bin/clonepack repo list
|
|
|
|
# Détail d'un dépôt
|
|
./bin/clonepack repo get 1
|
|
|
|
# Modifier un dépôt (source URL, sync mode, config APT)
|
|
./bin/clonepack repo update 1 --source-url https://archive.debian.org/debian
|
|
./bin/clonepack repo update 1 --suite bookworm-backports
|
|
./bin/clonepack repo update 1 --components main,contrib,non-free
|
|
./bin/clonepack repo update 1 --sync-mode manual
|
|
|
|
# Supprimer un dépôt
|
|
./bin/clonepack repo delete 1
|
|
```
|
|
|
|
Les flags `--suite`, `--components` et `--arch` ne s'appliquent qu'aux dépôts de type `apt`.
|
|
Seuls les flags fournis sont modifiés — les autres champs restent inchangés.
|
|
|
|
### Clonage
|
|
|
|
```bash
|
|
# Lancer le clonage complet d'un dépôt (télécharge tous les paquets)
|
|
./bin/clonepack repo clone 1
|
|
```
|
|
|
|
Le clonage est asynchrone : la commande affiche la progression du job jusqu'à completion.
|
|
|
|
### Synchronisation
|
|
|
|
```bash
|
|
# Déclencher un scan pour détecter les nouveaux paquets
|
|
./bin/clonepack repo sync 1
|
|
|
|
# Lister les paquets en attente de validation (mode manual)
|
|
./bin/clonepack repo sync-list 1
|
|
|
|
# Approuver des paquets spécifiques (téléchargement en arrière-plan)
|
|
./bin/clonepack repo sync-approve 1 42 43 44
|
|
|
|
# Approuver tous les paquets en attente
|
|
./bin/clonepack repo sync-approve 1 --all
|
|
|
|
# Rejeter des paquets (ils réapparaîtront au prochain scan)
|
|
./bin/clonepack repo sync-reject 1 42
|
|
```
|
|
|
|
Le scheduler tourne automatiquement selon l'intervalle configuré (`sync.interval`). En mode `auto`, les nouveaux paquets sont téléchargés directement. En mode `manual`, ils s'accumulent dans la liste d'attente.
|
|
|
|
### Blocklist
|
|
|
|
Les paquets bloqués n'apparaissent plus jamais dans la liste pending, quelle que soit leur version.
|
|
|
|
```bash
|
|
# Bloquer définitivement un paquet (par ID de la liste pending)
|
|
# → bloque la version exacte ET toutes les futures versions du même paquet
|
|
./bin/clonepack repo sync-block 1 42 43
|
|
|
|
# Voir les paquets bloqués
|
|
./bin/clonepack repo sync-blocklist 1
|
|
|
|
# Débloquer (par ID de la liste blocked)
|
|
./bin/clonepack repo sync-unblock 1 1 2
|
|
```
|
|
|
|
### Snapshots
|
|
|
|
```bash
|
|
# Créer un snapshot manuellement
|
|
./bin/clonepack repo snapshot create 1
|
|
./bin/clonepack repo snapshot create 1 --label "avant-mise-a-jour"
|
|
|
|
# Lister les snapshots d'un dépôt
|
|
./bin/clonepack repo snapshot list 1
|
|
|
|
# Détail d'un snapshot (métadonnées + liste des paquets)
|
|
./bin/clonepack repo snapshot show 1 3
|
|
|
|
# Comparer deux snapshots
|
|
./bin/clonepack repo snapshot diff 1 2 3
|
|
|
|
# Rollback vers un snapshot (supprime les paquets intrus, re-télécharge les manquants)
|
|
./bin/clonepack repo snapshot rollback 1 2
|
|
|
|
# Supprimer un snapshot
|
|
./bin/clonepack repo snapshot delete 1 3
|
|
```
|
|
|
|
Un snapshot automatique est créé après chaque `sync-approve` sur un dépôt RPM.
|
|
|
|
---
|
|
|
|
## Proxy miroir
|
|
|
|
ClonePack expose chaque dépôt cloné comme un miroir HTTP. L'accès est possible par **ID numérique** ou par **nom du dépôt** :
|
|
|
|
```
|
|
http://<host>:<port>/mirror/<repo_id>/
|
|
http://<host>:<port>/mirror/<nom_du_depot>/
|
|
```
|
|
|
|
Le proxy sert uniquement ce qui a été cloné localement (mode local-only). Si un fichier est absent, le serveur retourne 404.
|
|
|
|
**Configuration YUM/DNF** (`/etc/yum.repos.d/clonepack.repo`) :
|
|
```ini
|
|
[rocky9-baseos]
|
|
name=Rocky Linux 9 BaseOS via ClonePack
|
|
baseurl=http://clonepack:8080/mirror/rocky9-baseos
|
|
enabled=1
|
|
gpgcheck=0
|
|
```
|
|
|
|
**Configuration APT** (`/etc/apt/sources.list.d/clonepack.list`) :
|
|
```
|
|
deb [trusted=yes] http://clonepack:8080/mirror/debian-bookworm bookworm main contrib
|
|
```
|
|
|
|
---
|
|
|
|
## API REST
|
|
|
|
| Méthode | Route | Action |
|
|
|---------|-------|--------|
|
|
| `GET` | `/health` | Santé du serveur |
|
|
| `POST` | `/api/v1/repos` | Créer un dépôt |
|
|
| `GET` | `/api/v1/repos` | Lister les dépôts |
|
|
| `GET` | `/api/v1/repos/{id}` | Détail d'un dépôt |
|
|
| `PATCH` | `/api/v1/repos/{id}` | Modifier un dépôt |
|
|
| `DELETE` | `/api/v1/repos/{id}` | Supprimer un dépôt |
|
|
| `POST` | `/api/v1/repos/{id}/clone` | Démarrer le clonage |
|
|
| `GET` | `/api/v1/repos/{id}/clone/status` | Statut du clonage |
|
|
| `POST` | `/api/v1/repos/{id}/sync/trigger` | Déclencher un scan |
|
|
| `GET` | `/api/v1/repos/{id}/sync/pending` | Paquets en attente |
|
|
| `POST` | `/api/v1/repos/{id}/sync/approve` | Approuver des paquets |
|
|
| `POST` | `/api/v1/repos/{id}/sync/reject` | Rejeter des paquets |
|
|
| `POST` | `/api/v1/repos/{id}/sync/block` | Bloquer définitivement des paquets |
|
|
| `POST` | `/api/v1/repos/{id}/sync/unblock` | Débloquer des paquets |
|
|
| `GET` | `/api/v1/repos/{id}/sync/blocked` | Lister les paquets bloqués |
|
|
| `POST` | `/api/v1/repos/{id}/snapshots` | Créer un snapshot |
|
|
| `GET` | `/api/v1/repos/{id}/snapshots` | Lister les snapshots |
|
|
| `GET` | `/api/v1/repos/{id}/snapshots/{snap_id}` | Détail d'un snapshot |
|
|
| `DELETE` | `/api/v1/repos/{id}/snapshots/{snap_id}` | Supprimer un snapshot |
|
|
| `GET` | `/api/v1/repos/{id}/snapshots/diff?from=X&to=Y` | Diff deux snapshots |
|
|
| `POST` | `/api/v1/repos/{id}/snapshots/{snap_id}/rollback` | Rollback |
|
|
| `GET` | `/mirror/{id_ou_nom}/*` | Proxy miroir HTTP |
|
|
|
|
**Exemple de création d'un dépôt APT via REST :**
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/repos \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "debian-bookworm",
|
|
"type": "apt",
|
|
"source_url": "https://deb.debian.org/debian",
|
|
"apt_suite": "bookworm",
|
|
"apt_components": ["main", "contrib"],
|
|
"apt_architectures": ["amd64"],
|
|
"sync_mode": "manual"
|
|
}'
|
|
```
|
|
|
|
**Exemple de modification via REST :**
|
|
```bash
|
|
curl -X PATCH http://localhost:8080/api/v1/repos/1 \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"source_url": "https://archive.debian.org/debian", "apt_suite": "buster"}'
|
|
```
|