Files

groales a4e97a14a7 Agregar instrucción de Additional paths para Traefik en despliegue Portainer

2025-12-04 10:38:33 +01:00

15 KiB

Raw Blame History

NetBox

IPAM (IP Address Management) y DCIM (Data Center Infrastructure Management) de código abierto. Solución completa para documentar y gestionar infraestructura de red.

Características

📊 IPAM completo: Gestión de direcciones IP, VLANs, VRFs
🖥️ DCIM: Inventario de racks, dispositivos, cables
🔌 Gestión de circuitos: Proveedores, circuitos, conexiones
📝 Documentación: Custom fields, tags, journaling
🔗 API REST: Integración completa con sistemas externos
🔐 Multi-tenancy: Soporte para múltiples organizaciones
📈 Reportes: Visualización y exportación de datos
🔄 Webhooks: Automatización y notificaciones

Requisitos Previos

Docker Engine instalado
Portainer configurado (recomendado)
Para Traefik o NPM: Red Docker proxy creada
Dominio configurado: Para acceso HTTPS
Contraseñas generadas: DB_PASSWORD, REDIS_PASSWORD y SUPERUSER_PASSWORD

⚠️ IMPORTANTE: NetBox requiere PostgreSQL 18 y Redis. Este compose incluye ambos contenedores.

Sobre Redis

Redis se utiliza como caché de sesiones y tareas:

✅ tmpfs (RAM): Más rápido, no usa disco
🔒 Contraseña requerida: Seguridad defense-in-depth
⚡ No persistente: El caché se regenera automáticamente al reiniciar
💾 No requiere backup: Solo almacena datos temporales

Generar Contraseñas

Antes de cualquier despliegue, genera contraseñas seguras:

# DB_PASSWORD (PostgreSQL)
openssl rand -base64 32

# REDIS_PASSWORD
openssl rand -base64 32

# SUPERUSER_PASSWORD (admin de NetBox)
openssl rand -base64 32

Guarda los resultados, los necesitarás en el archivo .env.

⚠️ Importante: Usa comillas simples en el archivo .env si las contraseñas contienen caracteres especiales. Ejemplo: DB_PASSWORD='tu_password_generado'

Despliegue con Portainer

Opción A: Git Repository (Recomendada)

Permite mantener la configuración actualizada automáticamente desde Git.

En Portainer, ve a Stacks → Add stack
Nombra el stack: netbox
Selecciona Git Repository
Configura:
- Repository URL: https://git.ictiberia.com/groales/netbox
- Repository reference: refs/heads/main
- Compose path: docker-compose.yml
- GitOps updates: Activado (opcional - auto-actualización)
Solo para Traefik: En Additional paths, añade:
- docker-compose.override.traefik.yml.example
En Environment variables, añade:

DB_PASSWORD=tu_password_generado_1
REDIS_PASSWORD=tu_password_generado_2
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=tu_password_generado_3

Solo para Traefik: Añade también DOMAIN_HOST=netbox.example.com
Click en Deploy the stack

Opción B: Web editor

Para personalización completa del compose.

En Portainer, ve a Stacks → Add stack
Nombra el stack: netbox
Selecciona Web editor
Pega el contenido de docker-compose.yml
En Environment variables, añade las mismas variables que la Opción A
Click en Deploy the stack

Modos de Despliegue

Traefik (Proxy Inverso con SSL automático)

Requisitos:

Stack de Traefik desplegado
Red proxy creada
DNS apuntando al servidor

Pasos:

Copia el archivo de ejemplo:

cp docker-compose.override.traefik.yml.example docker-compose.override.traefik.yml

Edita docker-compose.override.traefik.yml y cambia ${DOMAIN_HOST} si es necesario
En Portainer, en las Environment variables del stack, añade:
```
DOMAIN_HOST=netbox.tudominio.com
```
Sube el archivo docker-compose.override.traefik.yml como Additional file:
- Path: docker-compose.override.traefik.yml
- Contenido: pega el contenido del archivo
Despliega el stack
Accede a https://netbox.tudominio.com

Ejemplo de compose completo con Traefik:

services:
  netbox:
    container_name: netbox
    image: lscr.io/linuxserver/netbox:latest
    restart: unless-stopped
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/Madrid
      SUPERUSER_EMAIL: ${SUPERUSER_EMAIL}
      SUPERUSER_PASSWORD: ${SUPERUSER_PASSWORD}
      ALLOWED_HOST: ${ALLOWED_HOST}
      DB_NAME: ${DB_NAME:-netbox}
      DB_USER: ${DB_USER:-netbox}
      DB_PASSWORD: ${DB_PASSWORD}
      DB_HOST: netbox-db
      DB_PORT: 5432
      REDIS_HOST: netbox-redis
      REDIS_PORT: 6379
      REDIS_PASSWORD: ${REDIS_PASSWORD}
    volumes:
      - netbox_config:/config
    networks:
      - proxy
      - netbox-internal
    depends_on:
      - netbox-db
      - netbox-redis
    labels:
      - traefik.enable=true
      - traefik.http.routers.netbox-http.rule=Host(`${DOMAIN_HOST}`)
      - traefik.http.routers.netbox-http.entrypoints=web
      - traefik.http.routers.netbox-http.middlewares=redirect-to-https
      - traefik.http.routers.netbox.rule=Host(`${DOMAIN_HOST}`)
      - traefik.http.routers.netbox.entrypoints=websecure
      - traefik.http.routers.netbox.tls=true
      - traefik.http.routers.netbox.tls.certresolver=letsencrypt
      - traefik.http.routers.netbox.service=netbox-svc
      - traefik.http.services.netbox-svc.loadbalancer.server.port=8000
      - traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https
      - traefik.http.middlewares.redirect-to-https.redirectscheme.permanent=true

  netbox-db:
    container_name: netbox-db
    image: postgres:18-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${DB_NAME:-netbox}
      POSTGRES_USER: ${DB_USER:-netbox}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - netbox_db:/var/lib/postgresql
    networks:
      - netbox-internal

  netbox-redis:
    container_name: netbox-redis
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD}
    tmpfs:
      - /data:rw,noexec,nosuid,size=256m
    networks:
      - netbox-internal

volumes:
  netbox_config:
    name: netbox_config
  netbox_db:
    name: netbox_db

networks:
  proxy:
    external: true
  netbox-internal:
    name: netbox-internal

Nginx Proxy Manager (NPM)

Requisitos:

NPM desplegado y accesible
Red proxy creada
DNS apuntando al servidor

Pasos:

Despliega el stack con el docker-compose.yml base (sin override)
En NPM, crea un nuevo Proxy Host:
- Domain Names: netbox.tudominio.com
- Scheme: http
- Forward Hostname / IP: netbox
- Forward Port: 8000
- Cache Assets: ✅ Activado
- Block Common Exploits: ✅ Activado
- Websockets Support: ✅ Activado
En la pestaña SSL:
- SSL Certificate: Request a new SSL Certificate (Let's Encrypt)
- Force SSL: ✅ Activado
- HTTP/2 Support: ✅ Activado
- HSTS Enabled: ✅ Activado (opcional)
Guarda y accede a https://netbox.tudominio.com

Configuración Inicial

Primer Acceso

Accede a NetBox usando tu dominio configurado
Haz login con las credenciales del superusuario:
- Email: El configurado en SUPERUSER_EMAIL
- Password: El configurado en SUPERUSER_PASSWORD
NetBox creará automáticamente la base de datos en el primer inicio (puede tardar 1-2 minutos)

Panel de Administración

Ve a Admin (esquina superior derecha) → Admin Panel
Configura los parámetros básicos:

Users & Groups

Crea usuarios adicionales en Users → Add
Define grupos y permisos en Groups
Asigna tokens de API en Tokens

Sites & Racks

Crea sitios (locations) en DCIM → Sites
Define racks y ubicaciones físicas
Configura regiones y tenant groups

IP Management

Define prefijos de red en IPAM → Prefixes
Crea VLANs en IPAM → VLANs
Configura VRFs si usas routing avanzado

Device Types

Importa tipos de dispositivos desde NetBox Device Type Library
O crea tipos personalizados en Device Types

Personalización

Configuración Avanzada

NetBox almacena su configuración en /config/ dentro del contenedor. Puedes personalizarla:

# Acceder al contenedor
docker exec -it netbox bash

# Editar configuración
nano /config/configuration.py

Configuraciones comunes:

# Banner personalizado
BANNER_TOP = 'NetBox Producción - ICT Iberia'
BANNER_BOTTOM = ''

# Preferencias de sesión
SESSION_COOKIE_AGE = 1209600  # 2 semanas

# Paginación
PAGINATE_COUNT = 50

# Tiempo de expiración de tokens
AUTH_TOKEN_TIMEOUT = 60 * 60 * 24 * 7  # 7 días

Reinicia el contenedor después de cambios: docker restart netbox

Plugins

NetBox soporta plugins para funcionalidad extendida. Instálalos en /config/plugins/:

# Ejemplo: NetBox Topology Views
docker exec -it netbox pip install netbox-topology-views

# Añadir a configuration.py
PLUGINS = ['netbox_topology_views']

# Reiniciar
docker restart netbox

LDAP / SSO

Configura autenticación LDAP editando /config/ldap_config.py:

import ldap
from django_auth_ldap.config import LDAPSearch

AUTH_LDAP_SERVER_URI = "ldap://ldap.example.com"
AUTH_LDAP_BIND_DN = "CN=netbox,OU=Services,DC=example,DC=com"
AUTH_LDAP_BIND_PASSWORD = "password"
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    "OU=Users,DC=example,DC=com",
    ldap.SCOPE_SUBTREE,
    "(sAMAccountName=%(user)s)"
)

Backup y Restauración

Backup Manual

# Backup de PostgreSQL
docker exec netbox-db pg_dump -U netbox netbox > netbox-backup-$(date +%Y%m%d).sql

# Backup de configuración
docker run --rm -v netbox_config:/backup -v $(pwd):/target alpine tar czf /target/netbox-config-$(date +%Y%m%d).tar.gz -C /backup .

# Redis usa tmpfs (no requiere backup - solo caché)

Backup Automático

Crea un script en /root/backup-netbox.sh:

#!/bin/bash
BACKUP_DIR="/backups/netbox"
DATE=$(date +%Y%m%d-%H%M%S)

mkdir -p $BACKUP_DIR

# PostgreSQL
docker exec netbox-db pg_dump -U netbox netbox | gzip > $BACKUP_DIR/netbox-db-$DATE.sql.gz

# Configuración
docker run --rm -v netbox_config:/backup -v $BACKUP_DIR:/target alpine tar czf /target/netbox-config-$DATE.tar.gz -C /backup .

# Limpiar backups antiguos (mantener 7 días)
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

echo "Backup completado: $DATE"

Programa con cron:

chmod +x /root/backup-netbox.sh
crontab -e

# Backup diario a las 2 AM
0 2 * * * /root/backup-netbox.sh

Restauración

# Detener NetBox
docker stop netbox

# Restaurar PostgreSQL
gunzip < netbox-db-20250101.sql.gz | docker exec -i netbox-db psql -U netbox netbox

# Restaurar configuración
docker run --rm -v netbox_config:/restore -v $(pwd):/source alpine tar xzf /source/netbox-config-20250101.tar.gz -C /restore

# Iniciar NetBox
docker start netbox

Actualización

Actualizar NetBox

# 1. Backup ANTES de actualizar
docker exec netbox-db pg_dump -U netbox netbox > netbox-pre-update-$(date +%Y%m%d).sql

# 2. Detener stack
docker stop netbox netbox-redis netbox-db

# 3. Actualizar imágenes
docker pull lscr.io/linuxserver/netbox:latest
docker pull postgres:18-alpine
docker pull redis:7-alpine

# 4. Iniciar stack
docker start netbox-db netbox-redis netbox

# 5. Verificar logs
docker logs -f netbox

# 6. Verificar versión en Admin Panel

Actualizar PostgreSQL

Si necesitas actualizar de PostgreSQL 16 a 18 (ya está en 18):

# 1. Backup
docker exec netbox-db pg_dump -U netbox netbox > netbox-pg-migration.sql

# 2. Detener y eliminar contenedor antiguo
docker stop netbox-db
docker rm netbox-db

# 3. Eliminar volumen antiguo
docker volume rm netbox_db

# 4. Recrear con PostgreSQL 18
docker compose up -d netbox-db

# 5. Restaurar datos
cat netbox-pg-migration.sql | docker exec -i netbox-db psql -U netbox netbox

# 6. Iniciar NetBox
docker start netbox

Solución de Problemas

NetBox no inicia

Síntomas: Contenedor se reinicia constantemente

Diagnóstico:

docker logs netbox

Soluciones:

Verificar que PostgreSQL esté funcionando: docker logs netbox-db
Verificar que Redis esté funcionando: docker logs netbox-redis
Comprobar contraseñas en .env
Verificar permisos del volumen: docker exec netbox ls -la /config

Error de conexión a base de datos

Síntomas: could not connect to server: Connection refused

Solución:

# Verificar que la BD esté lista
docker exec netbox-db pg_isready -U netbox

# Reiniciar servicios en orden
docker restart netbox-db
sleep 5
docker restart netbox-redis
sleep 5
docker restart netbox

Error de permisos

Síntomas: PermissionError: [Errno 13] Permission denied