Develop

.devcontainer/.env.example

@@ -31,3 +31,25 @@ SKIP_SUPERUSER=false
 #   .devcontainer/plugin-config.py.example → .devcontainer/plugin-config.py
 # Advanced NetBox configuration (optional):
 #   .devcontainer/extra-configuration.py.example → .devcontainer/extra-configuration.py
+
+# Proxy Configuration (optional, for corporate networks with MITM proxies)
+# Uncomment and set these if you're behind a proxy
+# HTTP_PROXY=http://proxy.example.com:8080
+# HTTPS_PROXY=http://proxy.example.com:8080
+# NO_PROXY=localhost,127.0.0.1,postgres,redis
+#
+# CA bundle configuration:
+# Normally you SHOULD NOT set REQUESTS_CA_BUNDLE, SSL_CERT_FILE, or CURL_CA_BUNDLE here.
+# Instead, place a ca-bundle.crt file in the workspace root and setup.sh will install it
+# into the system trust store and set these variables automatically to:
+#   /etc/ssl/certs/ca-certificates.crt
+# Only set the following manually for custom CA setups that cannot use the automatic
+# configuration provided by setup.sh.
+# REQUESTS_CA_BUNDLE=/custom/path/to/ca-bundle.crt
+# SSL_CERT_FILE=/custom/path/to/ca-bundle.crt
+# CURL_CA_BUNDLE=/custom/path/to/ca-bundle.crt
+
+# Git SSL verification override (default: false)
+# Only set to true if behind a MITM proxy and you cannot provide a CA bundle.
+# Prefer placing a ca-bundle.crt in the workspace root instead.
+# ALLOW_GIT_SSL_DISABLE=false

.devcontainer/README.md

@@ -65,6 +65,20 @@ If you need to test with a LibreNMS instance on a private network (local lab, co
 - **GitHub CLI**: Automatically configured for easy PR submission
 - **Logs**: Use `netbox-logs` to debug issues in real-time
 
+
+### 📡 LibreNMS Server Configuration
+
+You need a LibreNMS instance to use this plugin. Configure your LibreNMS server(s) in `plugin-config.py`:
+
+1. Copy the example config:
+
+   ```bash
+   cp .devcontainer/config/plugin-config.py.example .devcontainer/config/plugin-config.py
+   ```
+
+2. Edit it with your LibreNMS server URL(s) and API token(s)
+3. Restart NetBox: `netbox-restart`
+
 ## Out-of-the-box defaults
 
 Below are the dev container defaults. The field name to change these defaults is listed below each line.
@@ -139,6 +153,80 @@ You might experience issues with database schemas and migrations when changing N
 - Database: `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
 - Redis: `REDIS_HOST`, `REDIS_PASSWORD`
 - Superuser: `SUPERUSER_NAME`, `SUPERUSER_EMAIL`, `SUPERUSER_PASSWORD`, `SKIP_SUPERUSER`
+- Proxy: `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE`
+
+### 🌐 Proxy Configuration (MITM Proxies)
+
+If you're behind a corporate proxy or MITM proxy (like Zscaler, BlueCoat, etc.), you need to configure the proxy at two levels: the Docker client (for building) and the container runtime (for package installation inside the container).
+
+**Step 1: Configure Docker client proxy** (`~/.docker/config.json`)
+
+This is **required** so that `apt-get`, `curl`, etc. work during the container image build (e.g., when installing devcontainer features like `git` and `github-cli`).
+
+Create or edit `~/.docker/config.json`:
+
+```json
+{
+  "proxies": {
+    "default": {
+      "httpProxy": "http://proxy.example.com:8080",
+      "httpsProxy": "http://proxy.example.com:8080",
+      "noProxy": "localhost,127.0.0.1,postgres,redis"
+    }
+  }
+}
+```
+
+Docker automatically injects these as environment variables into every `RUN` instruction during `docker build`. No VS Code restart is needed — this takes effect immediately.
+
+> **Docker Desktop users:** You can configure the same settings via Docker Desktop Settings → Resources → Proxies, which writes this file for you.
+
+**Step 2: Create `.devcontainer/.env`** (for container runtime)
+
+```bash
+cp .devcontainer/.env.example .devcontainer/.env
+```
+
+Add your proxy settings to `.devcontainer/.env`:
+
+```bash
+# Proxy Configuration
+HTTP_PROXY=http://proxy.example.com:8080
+HTTPS_PROXY=http://proxy.example.com:8080
+NO_PROXY=localhost,127.0.0.1,postgres,redis
+```
+
+> **Note:** You do **not** need to set `REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, or `CURL_CA_BUNDLE` manually. When a `ca-bundle.crt` file is present in the workspace root, `setup.sh` automatically installs it into the system trust store and sets these variables to `/etc/ssl/certs/ca-certificates.crt`.
+
+**Step 3: Add your CA certificate** (optional, only if your proxy intercepts TLS):
+   - Export your proxy's CA certificate (usually available from your IT department or browser)
+   - Save it as `ca-bundle.crt` in the root of your workspace
+   - `setup.sh` will automatically install it and configure CA bundle environment variables
+
+**Step 4: Rebuild the container**:
+   - VS Code: Ctrl+Shift+P → "Dev Containers: Rebuild Container"
+
+**What gets configured:**
+- `~/.docker/config.json` → proxy for Docker build steps (devcontainer features, apt in Dockerfile)
+- `.devcontainer/.env` → proxy for running containers (apt, pip, curl at runtime)
+- `setup.sh` auto-configures apt proxy and git SSL settings inside the container
+
+**Important Notes:**
+- The `.env` file is ignored by git, so your proxy credentials stay private
+- `~/.docker/config.json` is a per-user file outside the repo
+- Add internal service names to `NO_PROXY` to avoid routing internal Docker traffic through the proxy
+- **Proxy authentication:** Embedding credentials directly in the proxy URL (e.g., `http://username:password@proxy.example.com:8080`) is insecure — credentials can be visible in process listings, environment dumps, `docker inspect` output, and logs. Prefer safer alternatives such as Docker's `config.json` with `credsStore` or a secret manager for storing proxy credentials securely.
+
+**Common Issues:**
+
+*"Could not connect to archive.ubuntu.com" during build*
+- → `~/.docker/config.json` is missing or has wrong proxy URL
+
+*"SSL certificate errors" during build*
+- → Your proxy uses a MITM certificate. Export it and add it to the system trust store, or set `SSL_CERT_FILE` in `.env`
+
+*Container builds but apt/pip fails inside*
+- → .env file is missing or has wrong proxy settings. Check .env matches Docker Desktop settings
 
 
 After any `.env` change, rebuild the dev container to apply environment updates.

.devcontainer/config/plugin-config.py.example

@@ -5,21 +5,21 @@ Default plugin configuration for the NetBox LibreNMS Plugin in the dev container
 - Copy this file to .devcontainer/plugin-config.py
 - Edit values as needed.
 
-- Add config for all other plugins here if any. 
+- Add config for all other plugins here if any.
 """
 
 # Ensure our plugin is enabled in dev (the loader sets this as a default too)
 PLUGINS = [
     "netbox_librenms_plugin",
 ]
 
-# Sample configuration with three example servers
+# Sample configuration with example servers
 PLUGINS_CONFIG = {
     "netbox_librenms_plugin": {
         "servers": {
             "production": {
                 "display_name": "Production LibreNMS",
-                "librenms_url": "https://librenms-prod.exampel.com",
+                "librenms_url": "https://librenms-prod.example.com",
                 "api_token": "your-prod-token",
                 "cache_timeout": 300,
                 "verify_ssl": True,

.devcontainer/devcontainer.json

@@ -34,12 +34,19 @@
     "SUPERUSER_NAME": "${localEnv:SUPERUSER_NAME:admin}",
     "SUPERUSER_EMAIL": "${localEnv:SUPERUSER_EMAIL:admin@example.com}",
     "SUPERUSER_PASSWORD": "${localEnv:SUPERUSER_PASSWORD:admin}",
-    "SKIP_SUPERUSER": "${localEnv:SKIP_SUPERUSER:false}"
-  },
-  "features": {
-    "ghcr.io/devcontainers/features/git:1": {},
-    "ghcr.io/devcontainers/features/github-cli:1": {}
+    "SKIP_SUPERUSER": "${localEnv:SKIP_SUPERUSER:false}",
+    "HTTP_PROXY": "${localEnv:HTTP_PROXY}",
+    "HTTPS_PROXY": "${localEnv:HTTPS_PROXY}",
+    "http_proxy": "${localEnv:HTTP_PROXY}",
+    "https_proxy": "${localEnv:HTTPS_PROXY}",
+    "NO_PROXY": "${localEnv:NO_PROXY}",
+    "no_proxy": "${localEnv:NO_PROXY}",
+    "REQUESTS_CA_BUNDLE": "${localEnv:REQUESTS_CA_BUNDLE}",
+    "SSL_CERT_FILE": "${localEnv:SSL_CERT_FILE}",
+    "CURL_CA_BUNDLE": "${localEnv:CURL_CA_BUNDLE}",
+    "ALLOW_GIT_SSL_DISABLE": "${localEnv:ALLOW_GIT_SSL_DISABLE:false}"
   },
+  "features": {},
   "customizations": {
     "vscode": {
       "extensions": [
@@ -72,4 +79,4 @@
   "postCreateCommand": "bash .devcontainer/scripts/setup.sh",
   "postAttachCommand": "bash .devcontainer/scripts/welcome.sh",
   "remoteUser": "root"
-}
+}

.devcontainer/docker-compose.yml

@@ -22,6 +22,17 @@ services:
       SUPERUSER_EMAIL: ${SUPERUSER_EMAIL:-admin@example.com}
       SUPERUSER_PASSWORD: ${SUPERUSER_PASSWORD:-admin}
       SKIP_SUPERUSER: ${SKIP_SUPERUSER:-false}
+      # Proxy settings (optional)
+      HTTP_PROXY: ${HTTP_PROXY:-}
+      HTTPS_PROXY: ${HTTPS_PROXY:-}
+      http_proxy: ${HTTP_PROXY:-}
+      https_proxy: ${HTTPS_PROXY:-}
+      NO_PROXY: ${NO_PROXY:-}
+      no_proxy: ${NO_PROXY:-}
+      REQUESTS_CA_BUNDLE: ${REQUESTS_CA_BUNDLE:-}
+      SSL_CERT_FILE: ${SSL_CERT_FILE:-}
+      CURL_CA_BUNDLE: ${CURL_CA_BUNDLE:-}
+      ALLOW_GIT_SSL_DISABLE: ${ALLOW_GIT_SSL_DISABLE:-false}
     depends_on:
       postgres:
         condition: service_healthy

.devcontainer/scripts/load-aliases.sh

@@ -61,4 +61,7 @@ alias rq-jobs="cd /opt/netbox/netbox && source /opt/netbox/venv/bin/activate &&
 alias rq-failed="cd /opt/netbox/netbox && source /opt/netbox/venv/bin/activate && python manage.py shell -c \"from django_rq import get_failed_queue; q = get_failed_queue(); print(f'Failed jobs: {len(q)}'); [print(f'  {job.id[:8]}: {job.func_name}') for job in q.jobs[:10]]\""
 alias rq-recent="cd /opt/netbox/netbox && source /opt/netbox/venv/bin/activate && python manage.py shell -c \"from core.models import Job; jobs = Job.objects.all().order_by('-created')[:10]; [print(f'{j.id}: {j.name[:50]} - {getattr(j.status, \\\"value\\\", j.status)} ({j.user})') for j in jobs]\""
 
-echo "✅ Aliases loaded! Try: rq-status, rq-stats, rq-recent"
+# Help
+alias dev-help='echo "🎯 NetBox LibreNMS Plugin Development Commands:"; echo ""; echo "📊 NetBox Server Management:"; echo "  netbox-run-bg       : Start NetBox in background"; echo "  netbox-run          : Start NetBox in foreground (for debugging)"; echo "  netbox-stop         : Stop NetBox and RQ worker"; echo "  netbox-restart      : Restart NetBox and RQ worker"; echo "  netbox-reload       : Reinstall plugin and restart NetBox"; echo "  netbox-status       : Check if NetBox and RQ worker are running"; echo "  netbox-logs         : View NetBox server logs"; echo ""; echo "⚙️  Background Jobs (RQ Worker):"; echo "  rq-status           : Check if RQ worker is running"; echo "  rq-logs             : View RQ worker logs"; echo "  rq-stats            : Show RQ queue statistics"; echo "  rq-jobs             : List jobs in default queue"; echo "  rq-failed           : List failed jobs"; echo "  rq-recent           : Show recent NetBox jobs"; echo ""; echo "🛠️  Development Tools:"; echo "  netbox-shell        : Open NetBox Django shell"; echo "  netbox-test         : Run plugin tests"; echo "  netbox-manage       : Run Django management commands"; echo "  plugin-install      : Reinstall plugin in development mode"; echo ""; echo "🧹 Code Quality:"; echo "  ruff-check          : Check code with Ruff"; echo "  ruff-format         : Format code with Ruff"; echo "  ruff-fix            : Auto-fix code issues with Ruff"; echo ""; echo "🔎 Diagnostics:"; echo "  diagnose            : Run startup diagnostics"; echo "  dev-help            : Show this help message"; echo ""; echo "📖 NetBox available at: http://localhost:8000 (admin/admin)"; echo ""'
+
+echo "✅ Aliases loaded! Try: rq-status, rq-stats, rq-recent, dev-help"