Saltar a contenido

Hetzner VPS Setup - Documentación Completa

Configuración profesional de un VPS en Hetzner Cloud con Docker, Nginx, SSL y subdominios

Version Status VPS Docker Nginx

📋 Índice

Guías de Configuración

  1. 🔒 Seguridad - SSH, Firewalls, Fail2ban
  2. 🐳 Docker - Docker y Docker Compose
  3. ⚙️ Nginx - Proxy Reverso y Configuración
  4. 🔐 SSL y Cloudflare - Certificados con DNS-01
  5. 🌐 Subdominios - Despliegue de aplicaciones
  6. 🤖 Claude Code - CLI de IA + Skill VPS para gestión automatizada
  7. 📚 MkDocs - Sitio web de documentación

Referencias Rápidas

🚀 Quick Start

Acceso al VPS

ssh your_username@YOUR_SERVER_IP

Gestión con Claude Code (Recomendado) 🤖

Este VPS está configurado con Claude Code, una CLI de IA que permite gestionar el sistema usando lenguaje natural:

# Iniciar Claude Code
claude

Luego puedes usar lenguaje natural para gestionar el VPS: 

"Chequea el estado del VPS"
"Reinicia la app labs"
"Limpia los contenedores Docker no usados"
"¿Cuánta memoria tengo libre?"

Beneficios: - ✅ No necesitas recordar comandos complejos - ✅ Claude conoce toda la infraestructura del VPS - ✅ Diagnóstico automático de problemas - ✅ Ejecución segura con validaciones

Ver Guía completa de Claude Code para instalación y uso detallado.

Ver estado del sistema

docker ps                    # Contenedores activos
sudo systemctl status nginx  # Estado de Nginx
sudo ufw status             # Estado del firewall
free -h                     # Uso de memoria

Crear nuevo subdominio

# Usar script de automatización
./scripts/new-subdomain.sh nombre-subdominio 3001

📊 Arquitectura del Sistema

Internet
   │
   ↓
Cloudflare DNS (proxy naranja)
   │
   ↓
Hetzner Cloud Firewall (80, 443)
   │
   ↓
VPS Ubuntu 24.04
   │
   ├─→ UFW Firewall
   │
   ├─→ Nginx (proxy reverso)
   │    │
   │    ├─→ :3000 → labs.josejordan.dev
   │    ├─→ :3001 → app.josejordan.dev
   │    └─→ :XXXX → otros subdominios
   │
   └─→ Docker Containers
        ├─→ labs (nginxdemos/hello)
        └─→ otras apps

💻 Especificaciones del VPS

Componente Especificación
Proveedor Hetzner Cloud
CPU 2 vCPU
RAM 4 GB
Swap 2 GB (configurado)
Disco 40 GB NVMe
Tráfico 20 TB/mes
Precio ~3-4€/mes
OS Ubuntu 24.04 LTS

✅ Estado de Configuración

Seguridad

  • [x] Usuario no-root con sudo
  • [x] Root login deshabilitado
  • [x] SSH con claves (password auth deshabilitado)
  • [x] SSH endurecido (MaxAuthTries 3, algoritmos cuánticos)
  • [x] Hetzner Cloud Firewall configurado
  • [x] UFW con políticas restrictivas
  • [x] Fail2ban activo
  • [x] Actualizaciones automáticas de seguridad

Infraestructura

  • [x] Docker 28.2.2 instalado
  • [x] Docker Compose v2.40.1 (moderno)
  • [x] Docker Compose v1.29.2 (legacy - disponible)
  • [x] Nginx como proxy reverso
  • [x] Certbot con DNS-01 (Cloudflare)
  • [x] Memoria Swap 2GB (swappiness=10)
  • [x] Zona horaria: Europe/Madrid

Herramientas de Gestión

  • [x] Claude Code CLI instalado
  • [x] VPS Skill configurada (gestión automatizada con IA)

Aplicaciones

  • [x] labs.josejordan.dev - Demo funcionando con HTTPS
  • [ ] Otros subdominios (pendiente)

🎯 Stack Tecnológico

┌─────────────────────────────────────────┐
│         Cloudflare (DNS + CDN)          │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         Nginx (Proxy Reverso)           │
│  - SSL/TLS (Let's Encrypt DNS-01)       │
│  - Virtual Hosts por subdominio         │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│       Docker + Docker Compose           │
│  - Aislamiento de aplicaciones          │
│  - Fácil despliegue y gestión           │
└─────────────────────────────────────────┘

📚 Recursos Externos

🔄 Flujo de Trabajo Típico

Desplegar Nueva Aplicación

  1. Preparar la aplicación 

    mkdir -p ~/apps/nombre-app
cd ~/apps/nombre-app
# Crear docker-compose.yml

  2. Configurar DNS en Cloudflare

  3. Crear registro A: nombre-app.josejordan.dev → IP del VPS

  4. Activar proxy naranja

  5. Configurar Nginx 

    sudo nano /etc/nginx/sites-available/nombre-app
sudo ln -s /etc/nginx/sites-available/nombre-app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

  6. Obtener certificado SSL 

    sudo certbot certonly --dns-cloudflare \
  --dns-cloudflare-credentials /root/.secrets/cf.ini \
  --cert-name nombre-app.josejordan.dev \
  -d nombre-app.josejordan.dev

  7. Iniciar la aplicación 

    docker compose up -d

Tip: Usa el script scripts/new-subdomain.sh para automatizar pasos 3-5

🆘 Problemas Comunes

Si tienes problemas, consulta la Guía de Troubleshooting.

Accesos rápidos: - No puedo conectar por SSH → Solución - Nginx no arranca → Solución - Docker sin permisos → Solución - SSL no funciona → Solución

📝 Notas Importantes

  • Doble firewall: Siempre configurar puertos en Hetzner Cloud Y UFW
  • Recursos limitados: 4GB RAM + 2GB Swap - no sobrecargar el VPS
  • Backup: Considerar snapshots de Hetzner o scripts personalizados
  • Monitoreo: Revisar regularmente con htop, docker stats, free -h
  • Renovación SSL: Automática cada 60 días con certbot.timer

📰 Historial de Cambios

Consulta el CHANGELOG.md para ver: - Historial completo de cambios - Versiones y fechas - Decisiones técnicas y migraciones - Actualizaciones de infraestructura

Versión actual: 2.0.0 (2025-11-02)

🤝 Contribuir

Este es un repositorio personal de documentación, pero las sugerencias son bienvenidas.

Para reportar errores o sugerir mejoras, crea un issue.

📄 Licencia

Documentación de uso personal.

Última actualización: Noviembre 2025 Mantenedor: @mundodigitalpro