From 067fb69c8f54e7aa84979f27b005968e32829ff6 Mon Sep 17 00:00:00 2001
From: Damien Arnodo <damien@noreply.localhost>
Date: Sun, 7 Dec 2025 17:18:14 +0000
Subject: [PATCH] docs: add comprehensive README

---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 55 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index cebae27..2b11ca7 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,56 @@
-# docker-images
+# Docker Images
 
-Custom Docker images built with Buildkit and hosted on Gitea Container Registry
\ No newline at end of file
+Dépôt centralisé pour les images Docker custom, buildées avec Buildkit et hébergées sur le registry Gitea.
+
+## Structure
+
+```
+docker-images/
+├── .gitea/workflows/
+│   └── build-images.yml    # Pipeline Buildkit
+├── images/
+│   ├── terraform-ci/       # Image Terraform + tflint
+│   │   ├── Dockerfile
+│   │   └── README.md
+│   └── <future-image>/
+└── README.md
+```
+
+## Fonctionnement
+
+Le workflow détecte automatiquement quelles images ont changé et ne rebuild que celles-ci.
+
+### Build automatique
+
+Push sur `main` avec des modifications dans `images/` → build et push automatique.
+
+### Build manuel
+
+Utiliser "Run workflow" dans l'interface Gitea Actions et spécifier le nom de l'image.
+
+## Images disponibles
+
+| Image | Description | Tags |
+|-------|-------------|------|
+| `terraform-ci` | Terraform 1.5.7 + tflint | `latest`, `<commit-sha>` |
+
+## Utilisation
+
+```bash
+# Pull depuis le registry Gitea
+docker pull gitea.arnodo.fr/damien/terraform-ci:latest
+```
+
+## Configuration requise
+
+### Secret à configurer
+
+Dans les paramètres du repo → Secrets → Actions :
+
+- `REGISTRY_TOKEN` : Token Gitea avec les droits `write:package`
+
+### Génération du token
+
+1. Gitea → Settings → Applications → Access Tokens
+2. Créer un token avec le scope `write:package`
+3. Ajouter comme secret `REGISTRY_TOKEN`