Instalación y Configuración

Esta guía te ayudará a instalar y configurar NoxPanel en tu entorno.

Note

La instalación incluye configuración de base de datos, Nginx y Proxmox.

Requisitos Previos

  • Docker y Docker Compose (o Docker Swarm)

  • Servidor Proxmox configurado y accesible

  • Dominio (opcional, para producción)

  • Certificado SSL (recomendado para producción)

Instalación Rápida

  1. Clonar el repositorio:

    git clone https://github.com/ocentelles/NoxPanel.git
cd NoxPanel

  2. Configurar variables de entorno:

    cp env.example .env
# Editar .env con tus credenciales

  3. Ejecutar con Docker Compose:

    docker-compose -f docker-compose.example.yml up -d

  4. Acceder al panel:

Note

La documentación se construye automáticamente al arrancar el contenedor.

Configuración de Variables

Variables Obligatorias:

# Base de datos
POSTGRES_DB=noxpanel
POSTGRES_USER=noxpanel
POSTGRES_PASSWORD=tu_password_seguro

# Django
SECRET_KEY=tu_secret_key_muy_largo
ALLOWED_HOSTS=localhost,127.0.0.1,tu-dominio.com

# Superusuario (se crea automáticamente)
DJANGO_SUPERUSER_USERNAME=admin
DJANGO_SUPERUSER_EMAIL=admin@tu-dominio.com
DJANGO_SUPERUSER_PASSWORD=Admin123456!

# Proxmox
PROXMOX_USER=root@pam
PROXMOX_PASSWORD=tu_password_proxmox
PROXMOX_API_INTERNAL=https://tu-ip-proxmox:8006

Variables Opcionales:

# Configuración del sitio
SITE_DOMAIN=tu-dominio.com
SITE_NAME=NoxPanel
DEBUG=False

# SSL (si usas proxy reverso)
SECURE_SSL_REDIRECT=False

Configuración de Nginx

Para Docker Compose:

# nginx.conf
server {
    listen 80;
    server_name tu-dominio.com;

    location / {
        proxy_pass http://web:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Para Docker Swarm:

# nginx.conf
server {
    listen 80;
    server_name tu-dominio.com;

    location / {
        proxy_pass http://tasks.webnox:8000;
        # ... resto igual
    }
}

Note

La documentación estará disponible en http://tu-dominio.com/docs/

Configuración de Proxmox

  1. Crear usuario en Proxmox:

    # En Proxmox
pveum user add noxpanel@pve
pveum aclmod / -user noxpanel@pve -role Administrator

  2. Configurar API Token (opcional):

    # Crear token
pveum user token add noxpanel@pve noxpanel-token

  3. Verificar conectividad:

    • Ir a Admin > Proxmox Nodes

    • Añadir tu servidor Proxmox

    • Probar conexión

Configuración de Pools

  1. Crear pools en Proxmox:

    # En Proxmox
pvesm add-pool development
pvesm add-pool production

  2. Sincronizar desde NoxPanel:

    • Ir a Admin > Pools

    • Los pools se sincronizan automáticamente

    • Configurar cuotas y permisos

Configuración de Usuarios

  1. Crear usuarios en Django:

    • Ir a Admin > Users

    • Crear usuarios con roles apropiados

  2. Asignar a pools:

    • Ir a Admin > Pool Memberships

    • Asignar usuarios a pools con roles

  3. Configurar permisos:

    • Owner: Control total

    • Admin: Gestión de VMs

    • User: Crear y controlar VMs

    • Read-only: Solo visualización

Verificación de Instalación

Comprobar servicios:

# Verificar contenedores
docker-compose ps

# Ver logs
docker-compose logs web

# Verificar salud
curl http://localhost/health/

Comprobar funcionalidades:

  1. Acceso al panel: http://localhost

  2. Documentación: http://localhost/docs/

  3. Admin Django: http://localhost/admin/

  4. Conexión Proxmox: Probar desde admin

  5. Crear VM: Probar creación de VM

Troubleshooting

Problemas Comunes:

  1. Error de conexión a base de datos:

    # Verificar PostgreSQL
docker-compose logs db

# Reiniciar servicios
docker-compose restart

  2. Error de permisos de staticfiles:

    # El entrypoint maneja esto automáticamente
# Si persiste, ejecutar manualmente:
docker-compose exec web chown -R django:django /app/staticfiles

  3. Documentación no accesible:

    # Verificar construcción de docs
docker-compose logs web | grep "Documentation"

# Reconstruir manualmente
docker-compose exec web bash -c "cd /app/docs && sphinx-build -b html . _build/html"

  4. Error de conexión a Proxmox:

    • Verificar credenciales en .env

    • Comprobar conectividad de red

    • Verificar configuración SSL

Actualización

Actualizar NoxPanel:

# Parar servicios
docker-compose down

# Actualizar código
git pull origin master

# Reconstruir imagen
docker-compose build

# Reiniciar servicios
docker-compose up -d

Migración de datos:

# Backup de base de datos
docker-compose exec db pg_dump -U noxpanel noxpanel > backup.sql

# Restaurar backup
docker-compose exec -T db psql -U noxpanel noxpanel < backup.sql

Seguridad

Recomendaciones:

  1. Cambiar contraseñas por defecto

  2. Usar HTTPS en producción

  3. Configurar firewall

  4. Mantener actualizado

  5. Backups regulares

Configuración SSL:

# Con Let's Encrypt
server {
    listen 443 ssl;
    server_name tu-dominio.com;

    ssl_certificate /etc/letsencrypt/live/tu-dominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/tu-dominio.com/privkey.pem;

    location / {
        proxy_pass http://web:8000;
        # ... resto igual
    }
}

Próximos Pasos

Note

Para soporte adicional, consulta la documentación completa en /docs/ o abre un issue en GitHub.