Merge pull request 'fix: use system Python to fix venv symlink issue' (#4) from fix/netbox-mcp-python-venv into main

Reviewed-on: #4

.gitea/workflows/build-images.yml

@@ -89,11 +89,47 @@ jobs:
             fi
             
             echo "========================================"
-            echo "Building ${IMAGE_NAME}:latest"
+            echo "Building ${IMAGE_NAME}"
             echo "========================================"
             
-            docker build -t "${IMAGE_NAME}:latest" "${IMAGE_PATH}"
-            docker push "${IMAGE_NAME}:latest"
+            # Check for version file (format: <NAME>_VERSION or VERSION)
+            VERSION=""
+            BUILD_ARGS=""
             
-            echo "✅ Pushed ${IMAGE_NAME}:latest"
+            # Look for specific version file (e.g., NETBOX_VERSION, TERRAFORM_VERSION)
+            for version_file in "$IMAGE_PATH"/*_VERSION "$IMAGE_PATH"/VERSION; do
+              if [ -f "$version_file" ]; then
+                VERSION=$(cat "$version_file" | tr -d '[:space:]')
+                VERSION_NAME=$(basename "$version_file" | sed 's/_VERSION$//')
+                
+                if [ "$VERSION_NAME" = "VERSION" ]; then
+                  # Generic VERSION file
+                  echo "📌 Found VERSION file: $VERSION"
+                else
+                  # Specific version file (e.g., NETBOX_VERSION)
+                  echo "📌 Found ${VERSION_NAME}_VERSION file: $VERSION"
+                  BUILD_ARGS="--build-arg ${VERSION_NAME}_VERSION=${VERSION}"
+                fi
+                break
+              fi
+            done
+            
+            # Build the image with --no-cache to ensure fresh build
+            if [ -n "$BUILD_ARGS" ]; then
+              echo "🔧 Building with args: $BUILD_ARGS"
+              docker build --no-cache $BUILD_ARGS -t "${IMAGE_NAME}:latest" "$IMAGE_PATH"
+            else
+              docker build --no-cache -t "${IMAGE_NAME}:latest" "$IMAGE_PATH"
+            fi
+            
+            # Push latest tag
+            docker push "${IMAGE_NAME}:latest"
+            echo "✅ Pushed ${IMAGE_NAME}:latest"
+            
+            # Also tag and push with version if available
+            if [ -n "$VERSION" ]; then
+              docker tag "${IMAGE_NAME}:latest" "${IMAGE_NAME}:${VERSION}"
+              docker push "${IMAGE_NAME}:${VERSION}"
+              echo "✅ Pushed ${IMAGE_NAME}:${VERSION}"
+            fi
           done

images/netbox-mcp-server/Dockerfile

@@ -0,0 +1,62 @@
+# =============================================================================
+# NetBox MCP Server
+#
+# Image Docker pour le serveur MCP NetBox (Model Context Protocol)
+# Permet l'interaction read-only avec NetBox via LLMs
+# Source: https://github.com/netboxlabs/netbox-mcp-server
+# =============================================================================
+
+ARG NETBOX_MCP_VERSION=1.0.0
+
+# -----------------------------------------------------------------------------
+# Stage 1: Builder
+# -----------------------------------------------------------------------------
+FROM python:3.13-alpine3.21 AS builder
+
+ARG NETBOX_MCP_VERSION
+
+RUN apk add --no-cache git \
+    && pip install --root-user-action=ignore --no-cache-dir --upgrade pip \
+    && pip install --root-user-action=ignore --no-cache-dir uv
+
+ENV UV_LINK_MODE=copy
+ENV UV_PYTHON_PREFERENCE=only-system
+
+WORKDIR /app
+
+# Clone le repo à la version spécifiée
+RUN git clone --depth 1 --branch v${NETBOX_MCP_VERSION} \
+    https://github.com/netboxlabs/netbox-mcp-server.git .
+
+# Sync des dépendances avec cache uv
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev
+
+# -----------------------------------------------------------------------------
+# Stage 2: Runtime
+# -----------------------------------------------------------------------------
+FROM python:3.13-alpine3.21
+
+LABEL maintainer="Damien Arnodo"
+LABEL org.opencontainers.image.title="NetBox MCP Server"
+LABEL org.opencontainers.image.description="A read-only MCP server for NetBox"
+LABEL org.opencontainers.image.url="https://github.com/netboxlabs/netbox-mcp-server"
+LABEL org.opencontainers.image.source="https://github.com/netboxlabs/netbox-mcp-server"
+LABEL org.opencontainers.image.licenses="Apache-2.0"
+
+ENV PYTHONUNBUFFERED=1
+
+RUN apk add --no-cache ca-certificates \
+    && addgroup -g 1000 appuser \
+    && adduser -D -u 1000 -G appuser appuser
+
+COPY --from=builder --chown=appuser:appuser /app /app
+
+WORKDIR /app
+USER appuser
+
+ENV PATH="/app/.venv/bin:$PATH"
+
+EXPOSE 8000
+
+CMD ["netbox-mcp-server"]

images/netbox-mcp-server/NETBOX_MCP_VERSION

@@ -0,0 +1 @@
+1.0.0

images/netbox-mcp-server/README.md

@@ -0,0 +1,70 @@
+# NetBox MCP Server
+
+Image Docker pour le [NetBox MCP Server](https://github.com/netboxlabs/netbox-mcp-server) - serveur Model Context Protocol permettant l'interaction read-only avec NetBox via LLMs.
+
+## Usage avec Claude Desktop (STDIO)
+
+Configuration dans `claude_desktop_config.json` :
+
+```json
+{
+  "mcpServers": {
+    "netbox": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "NETBOX_URL",
+        "-e", "NETBOX_TOKEN",
+        "gitea.arnodo.fr/damien/netbox-mcp-server:latest"
+      ],
+      "env": {
+        "NETBOX_URL": "https://netbox.example.com/",
+        "NETBOX_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Usage en mode HTTP
+
+Pour les clients web MCP :
+
+```bash
+docker run --rm \
+  -e NETBOX_URL=https://netbox.example.com/ \
+  -e NETBOX_TOKEN=your-api-token \
+  -e TRANSPORT=http \
+  -p 8000:8000 \
+  gitea.arnodo.fr/damien/netbox-mcp-server:latest
+```
+
+Le serveur sera accessible sur `http://localhost:8000/mcp`.
+
+## Variables d'environnement
+
+| Variable | Défaut | Description |
+|----------|--------|-------------|
+| `NETBOX_URL` | - | URL de l'instance NetBox (requis) |
+| `NETBOX_TOKEN` | - | Token API NetBox read-only (requis) |
+| `TRANSPORT` | `stdio` | Transport MCP : `stdio` ou `http` |
+| `VERIFY_SSL` | `true` | Vérification des certificats SSL |
+| `LOG_LEVEL` | `INFO` | Niveau de log |
+| `HOST` | `0.0.0.0` | Adresse d'écoute (mode HTTP) |
+| `PORT` | `8000` | Port d'écoute (mode HTTP) |
+
+## Outils MCP disponibles
+
+| Outil | Description |
+|-------|-------------|
+| `get_objects` | Récupère les objets NetBox selon type et filtres |
+| `get_object_by_id` | Détails d'un objet par son ID |
+| `get_changelogs` | Historique des modifications |
+
+## Exemples de requêtes
+
+```
+> Liste tous les devices du site 'DC1'
+> Montre-moi l'utilisation IPAM
+> Qui a modifié le routeur principal cette semaine ?
+```

images/netbox/Dockerfile

@@ -0,0 +1,22 @@
+# =============================================================================
+# NetBox Docker Image with Plugins
+#
+# Image NetBox personnalisée avec plugins pré-installés
+# Basée sur l'image officielle netboxcommunity/netbox
+# =============================================================================
+
+ARG NETBOX_VERSION=latest
+FROM netboxcommunity/netbox:${NETBOX_VERSION}
+
+LABEL maintainer="Damien Arnodo"
+LABEL description="NetBox with pre-installed plugins for homelab use"
+
+# Copie du fichier de requirements des plugins
+COPY plugin_requirements.txt /opt/netbox/
+
+# Installation des plugins via uv pip (méthode officielle NetBox Docker)
+RUN /usr/local/bin/uv pip install --no-cache -r /opt/netbox/plugin_requirements.txt
+
+# NOTE: configuration.py et plugins.py doivent être montés au runtime
+# via docker-compose pour configurer DynamicSchemaDict et les plugins.
+# Voir: https://gitea.arnodo.fr/Damien/netbox-deployment

images/netbox/NETBOX_VERSION

@@ -0,0 +1 @@
+v4.4

images/netbox/README.md

@@ -0,0 +1,131 @@
+# NetBox Docker Image avec Plugins
+
+Image Docker NetBox personnalisée avec plugins pré-installés, construite automatiquement via Gitea Actions.
+
+## Plugins inclus
+
+Par défaut, les plugins suivants sont installés :
+
+| Plugin | Description | Version (pour NetBox 4.4.x) |
+|--------|-------------|----------------------------|
+| `netbox-branching` | Branching et change management (NetBox Labs) | 0.7.x |
+| `netbox-bgp` | Gestion des sessions BGP, peers, communities | 0.17.x |
+| `netbox-secrets` | Gestion sécurisée des secrets et mots de passe | latest |
+| `netbox-topology-views` | Visualisation de topologie réseau | latest |
+
+## Utilisation
+
+### Pull depuis le registry
+
+```bash
+# Dernière version
+docker pull gitea.arnodo.fr/damien/netbox:latest
+
+# Version spécifique
+docker pull gitea.arnodo.fr/damien/netbox:v4.4
+```
+
+### Avec Docker Compose
+
+Créer un `docker-compose.override.yml` pour utiliser l'image personnalisée :
+
+```yaml
+services:
+  netbox:
+    image: gitea.arnodo.fr/damien/netbox:v4.4
+    pull_policy: always
+  netbox-worker:
+    image: gitea.arnodo.fr/damien/netbox:v4.4
+    pull_policy: always
+  netbox-housekeeping:
+    image: gitea.arnodo.fr/damien/netbox:v4.4
+    pull_policy: always
+```
+
+## ⚠️ Configuration requise pour netbox-branching
+
+Le plugin `netbox-branching` nécessite une configuration spéciale de la base de données. Tu dois modifier ta configuration NetBox pour wrapper `DATABASES` avec `DynamicSchemaDict`.
+
+### Dans ton `configuration.py` ou via variables d'environnement :
+
+```python
+from netbox_branching.utilities import DynamicSchemaDict
+
+DATABASES = DynamicSchemaDict({
+    'default': {
+        'ENGINE': 'django.db.backends.postgresql',
+        'NAME': 'netbox',
+        'USER': 'netbox',
+        'PASSWORD': 'password',
+        'HOST': 'postgres',
+        'PORT': '',
+    }
+})
+
+DATABASE_ROUTERS = [
+    'netbox_branching.database.BranchAwareRouter',
+]
+```
+
+### Permissions PostgreSQL requises
+
+L'utilisateur PostgreSQL doit avoir la permission de créer des schemas :
+
+```sql
+GRANT CREATE ON DATABASE netbox TO netbox;
+```
+
+Voir la [documentation officielle netbox-branching](https://netboxlabs.com/docs/extensions/branching/) pour plus de détails.
+
+## Gestion des versions
+
+La version de NetBox est définie dans le fichier `NETBOX_VERSION`. Pour changer de version :
+
+1. Modifier le fichier `NETBOX_VERSION` avec la version souhaitée (ex: `v4.4`)
+2. **Mettre à jour les versions des plugins** dans `plugin_requirements.txt` si nécessaire
+3. Commit et push
+4. Le CI va automatiquement :
+   - Builder l'image avec cette version de NetBox
+   - Tagger l'image avec `latest` ET avec la version (ex: `v4.4`)
+
+### Compatibilité plugins / NetBox
+
+| NetBox | netbox-branching | netbox-bgp |
+|--------|------------------|------------|
+| 4.4.x  | 0.7.x            | 0.17.x     |
+| 4.5.x  | 0.8.x+           | 0.18.x+    |
+
+## Personnalisation des plugins
+
+### Ajouter un plugin
+
+1. Éditer `plugin_requirements.txt` et ajouter le package PyPI
+2. Éditer `plugins.py` et ajouter le plugin à la liste `PLUGINS`
+3. Configurer le plugin dans `PLUGINS_CONFIG` si nécessaire
+4. Commit et push - l'image sera rebuild automatiquement
+
+## Structure des fichiers
+
+```
+images/netbox/
+├── Dockerfile              # Image principale
+├── NETBOX_VERSION          # Version de NetBox à utiliser
+├── plugin_requirements.txt # Liste des plugins PyPI (avec versions)
+├── plugins.py              # Configuration des plugins
+└── README.md               # Cette documentation
+```
+
+## Plugins - Liens et documentation
+
+- **netbox-branching** : https://github.com/netboxlabs/netbox-branching
+- **netbox-bgp** : https://github.com/netbox-community/netbox-bgp
+- **netbox-secrets** : https://github.com/Onemind-Services-LLC/netbox-secrets
+- **netbox-topology-views** : https://github.com/netbox-community/netbox-topology-views
+
+## Notes
+
+- L'image utilise `uv pip` pour l'installation des plugins (méthode officielle NetBox Docker)
+- Les assets statiques sont collectés au premier démarrage (pas au build)
+- Compatible avec NetBox >= 4.0 (netbox-branching requiert NetBox 4.1+)
+- Le fichier `NETBOX_VERSION` contrôle la version de base et le tag de l'image
+- **Les versions des plugins sont fixées** pour garantir la compatibilité

images/netbox/plugin_requirements.txt

@@ -0,0 +1,29 @@
+# =============================================================================
+# NetBox Plugins Requirements
+# =============================================================================
+# Liste des plugins à installer dans l'image NetBox
+# Format: nom-du-package==version (ou sans version pour la dernière)
+#
+# IMPORTANT: Les versions sont fixées pour garantir la compatibilité avec
+# NetBox 4.4.x. Mettre à jour les versions lors du passage à NetBox 4.5+
+#
+# Documentation des plugins:
+# - netbox-branching: Branching et change management (NetBox Labs)
+#   https://github.com/netboxlabs/netbox-branching
+# - netbox-bgp: Gestion des sessions BGP, peers, communities
+#   https://github.com/netbox-community/netbox-bgp
+# - netbox-secrets: Gestion des secrets (remplace netbox-secretstore pour NetBox >= 3.5)
+# - netbox-topology-views: Visualisation de topologie réseau
+# =============================================================================
+
+# Plugins actifs - versions fixées pour NetBox 4.4.x
+netboxlabs-netbox-branching>=0.7.0,<0.8.0
+netbox-bgp>=0.17.0,<0.18.0
+netbox-secrets
+netbox-topology-views
+
+# Plugins disponibles - décommente ceux dont tu as besoin
+# netbox-documents
+# netbox-acls
+# netbox-qrcode
+# netbox-proxbox