A diferencia de Traefik, con NPM necesitas configurar WebSocket manualmente desde la interfaz web. Este paso es crítico para que la sincronización en tiempo real funcione correctamente.

📋 Requisitos Previos

Antes de comenzar, asegúrate de tener:

✅ Nginx Proxy Manager funcionando y accesible
✅ Red Docker proxy creada y NPM conectado a ella
✅ Dominio configurado apuntando a tu servidor
✅ Puertos 80 y 443 abiertos y dirigidos a NPM
✅ ADMIN_TOKEN generado

Verificar Red Proxy

docker network ls | grep proxy

Si no existe, créala:

docker network create proxy

🔑 Generar ADMIN_TOKEN

Antes de cualquier despliegue, genera un token en formato Argon2 seguro:

# 1. Generar token aleatorio
openssl rand -base64 48

# 2. Convertir a formato Argon2 seguro
docker run --rm -it vaultwarden/server:latest /vaultwarden hash
# Pega el token cuando lo solicite

Guarda el hash Argon2 resultante (empieza con $argon2id$ ), lo necesitarás para las variables de entorno.

⚠️ Importante: Usa comillas simples en el archivo .env para evitar que $ se interprete como variable.

🚀 Despliegue desde Portainer

Opción A: Git Repository (Recomendada)

Esta opción mantiene tu stack actualizado con el repositorio Git.

En Portainer, ve a Stacks → Add stack
Nombre del stack: vaultwarden
Selecciona Git Repository
Configura el repositorio:
- Repository URL: https://git.ictiberia.com/groales/vaultwarden
- Repository reference: refs/heads/main
- Compose path: docker-compose.yml
- Additional paths: Dejar vacío (no necesitas override para NPM)
En Environment variables, añade:

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'  # Entre comillas simples

⚠️ Nota: Otras opciones (DOMAIN, registros, SMTP) se configuran desde el panel /admin.

Haz clic en Deploy the stack

Opción B: Web Editor

Si prefieres tener el compose completo en Portainer:

En Portainer, ve a Stacks → Add stack
Nombre del stack: vaultwarden
Selecciona Web editor
Copia y pega este contenido:

services:
  vaultwarden:
    container_name: vaultwarden
    image: vaultwarden/server:latest
    restart: unless-stopped
    environment:
      ADMIN_TOKEN: ${ADMIN_TOKEN}
      TZ: Europe/Madrid
    volumes:
      - vaultwarden_data:/data
    networks:
      - proxy

volumes:
  vaultwarden_data:
    name: vaultwarden_data

networks:
  proxy:
    external: true

En Environment variables, añade las mismas variables que en la Opción A
Haz clic en Deploy the stack

🖥️ Despliegue desde CLI

1. Clonar el repositorio

git clone https://git.ictiberia.com/groales/vaultwarden.git
cd vaultwarden

2. Configurar variables de entorno

No necesitas archivo override. El docker-compose.yml base es suficiente para NPM.

cp .env.example .env

Edita el archivo .env y configura:

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$...'  # Entre comillas simples

3. Iniciar el servicio

docker compose up -d

4. Verificar el despliegue

# Ver logs
docker compose logs -f vaultwarden

# Verificar que el contenedor está corriendo
docker compose ps

5. Configurar Nginx Proxy Manager

Ver la sección de configuración a continuación.

🔧 Configuración en Nginx Proxy Manager

Una vez el contenedor está corriendo, debes configurar el Proxy Host en NPM.

1. Acceder a NPM

Ve a la interfaz web de Nginx Proxy Manager (normalmente http://tu-servidor:81).

2. Crear Proxy Host

Ve a Proxy Hosts → Add Proxy Host
En la pestaña Details:
- Domain Names: vaultwarden.tudominio.com
- Scheme: http (sí, HTTP, porque es interno)
- Forward Hostname / IP: vaultwarden (nombre del contenedor)
- Forward Port: 80
- ✅ Cache Assets: Activar
- ✅ Block Common Exploits: Activar
- ✅ Websockets Support: ⚠️ CRÍTICO - ACTIVAR
En la pestaña SSL:
- ✅ Force SSL: Activar
- SSL Certificate: Selecciona "Request a new SSL Certificate"
- ✅ Force SSL: Activar
- ✅ HTTP/2 Support: Activar
- ✅ HSTS Enabled: Activar (recomendado)
- Email: Tu email para Let's Encrypt
- ✅ I Agree to the Let's Encrypt Terms of Service
Haz clic en Save

3. Configuración Avanzada (Opcional)

Si quieres añadir headers de seguridad adicionales:

Edita el Proxy Host creado
Ve a la pestaña Advanced
Añade en Custom Nginx Configuration:

# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# WebSocket headers
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Guarda los cambios

⚠️ WebSocket Support - CRÍTICO

El WebSocket Support es imprescindible para Vaultwarden. Sin él:

❌ No habrá sincronización en tiempo real
❌ Los cambios tardarán minutos en aparecer en otros dispositivos
❌ La experiencia de usuario será deficiente

Verificar WebSocket

En NPM, edita el Proxy Host de Vaultwarden
En la pestaña Details, verifica que Websockets Support está ✅ activado
Si no lo está, actívalo y guarda

Probar WebSocket desde CLI

# Instalar wscat si no lo tienes
npm install -g wscat

# Probar conexión WebSocket
wscat -c wss://vaultwarden.tudominio.com/notifications/hub

Si funciona, verás una conexión establecida. Si falla, revisa la configuración de NPM.

✅ Verificación del Despliegue

1. Verificar Acceso Web

Abre tu navegador y ve a: https://vaultwarden.tudominio.com

Deberías ver la página de login/registro de Vaultwarden con certificado SSL válido (candado verde).

2. Verificar Certificado SSL

Haz clic en el candado del navegador y verifica:

✅ Certificado emitido por Let's Encrypt
✅ Válido y no caducado
✅ Sin errores de nombre de dominio

3. Verificar WebSocket en Logs

docker compose logs vaultwarden | grep -i websocket

Deberías ver:

[INFO] WebSocket server listening on 0.0.0.0:3012

4. Verificar Panel de Administración

Ve a: https://vaultwarden.tudominio.com/admin

Introduce tu ADMIN_TOKEN. Si puedes acceder, la configuración es correcta.

5. Prueba de Sincronización

Crea una cuenta en Vaultwarden
Añade una contraseña desde la interfaz web
Instala la app móvil de Bitwarden
Configura el servidor: https://vaultwarden.tudominio.com
Inicia sesión
La contraseña debería aparecer inmediatamente (si WebSocket funciona)

Si la sincronización tarda minutos, WebSocket NO está funcionando.

🔒 Seguridad Adicional

Restringir Acceso por IP al Admin Panel

Puedes limitar el acceso al panel /admin desde la configuración avanzada de NPM:

Edita el Proxy Host de Vaultwarden
Ve a Advanced
Añade:

# Permitir solo desde tu IP
location /admin {
    allow 192.168.1.100;  # Tu IP
    deny all;
    proxy_pass http://vaultwarden:80;
}

Headers de Seguridad

Ya añadidos en la configuración opcional anterior, incluyen:

X-Frame-Options: Previene clickjacking
X-Content-Type-Options: Previene MIME sniffing
X-XSS-Protection: Protección XSS
Referrer-Policy: Control de referrer

🔄 Actualización

Desde Portainer (Git Repository):

Ve al stack vaultwarden
Clic en Pull and redeploy

Desde CLI:

docker compose pull
docker compose up -d

Nota: No necesitas cambiar nada en NPM al actualizar, el Proxy Host seguirá funcionando.

📖 Siguientes Pasos

Configuración Inicial: Configura el panel de administración
Personalización: Ajusta SMTP, usuarios y organizaciones
Backup y Restauración: Protege tus datos

🆘 Solución de Problemas

Error 502 Bad Gateway

Síntoma: NPM muestra error 502

Solución:

Verifica que el contenedor está corriendo: docker compose ps
Comprueba que ambos están en la red proxy:
```
docker network inspect proxy
```
Verifica el nombre del contenedor es exactamente vaultwarden
Revisa logs de NPM y Vaultwarden

WebSocket no funciona

Síntoma: Sincronización muy lenta

Solución:

✅ Activa Websockets Support en el Proxy Host de NPM
Verifica en logs: docker compose logs vaultwarden | grep websocket
Limpia caché del navegador
Prueba con wscat como se indicó arriba

Certificado SSL no se renueva

Síntoma: Advertencia de certificado caducado

Solución:

En NPM, edita el Proxy Host
Pestaña SSL → Click en Force Renew
Verifica que el puerto 80 está abierto (Let's Encrypt lo necesita)
Revisa logs de NPM para errores de renovación

No puedo acceder al admin panel

Síntoma: Error al acceder a /admin

Solución:

Verifica que ADMIN_TOKEN está configurado correctamente
Prueba regenerar el token: openssl rand -base64 48
Actualiza las variables de entorno en Portainer
Redesplegar el stack

Última actualización: Diciembre 2025