📋 Prerrequisitos del sistema

Antes de comenzar, asegúrate de cumplir con los siguientes requisitos:

• VPS Linux: Ubuntu 22.04 LTS o Debian 12 recomendado (mínimo 2 vCPU, 4GB RAM)
• Docker Engine: versión 24.0+ instalada y configurada con Docker Compose plugin
• SSH con clave pública: acceso remoto seguro al servidor sin contraseña
• Let's Encrypt: para certificados TLS automáticos (acceso DNS o IP público)
• RAM disponible: mínimo 2GB para PostgreSQL + aplicaciones
• Espacio en disco: 10GB+ para datos, backups y logs
• Firewall externa: IONOS Cloud Panel o equivalente con puertos 22/80/443 abiertos

Nota: El script bootstrap-vps.sh no configura la firewall — esto se gestiona desde el panel de control del proveedor.

🚀 Despliegue inicial — bootstrap-vps.sh

El script scripts/bootstrap-vps.sh automatiza el provisionamiento completo del VPS. Este es un script one-shot que debe ejecutarse una sola vez como root.

Ejecución desde local:

# Conectarse al VPS
ssh root@<vps-ip>

# Descargar y ejecutar el script de bootstrap
curl -fsSL https://raw.githubusercontent.com/cykedev/vereinsheim/main/scripts/bootstrap-vps.sh | bash -s -- "ssh-ed25519 AAAA...tu-clave-publica" "https://github.com/cykedev/vereinsheim.git"

# Alternativa: descargar el script localmente
curl -fsSL https://raw.githubusercontent.com/cykedev/vereinsheim/main/scripts/bootstrap-vps.sh -o bootstrap-vps.sh
chmod +x bootstrap-vps.sh
./bootstrap-vps.sh "ssh-ed25519 AAAA..." "https://github.com/cykedev/vereinsheim.git"

Qué hace el script:

1. Actualiza paquetes: apt update + upgrade
2. Instala paquetes base: ca-certificates, curl, git, gnupg
3. Instala Docker Engine y Docker Compose plugin vía oficial script
4. Crea usuario deploy con sudo y docker-Group
5. Hace backup de SSH-key pública en ~/.ssh/authorized_keys
6. Clona el repositorio en /home/deploy/vereinsheim
7. Provisiona /var/backups/vereinsheim con owner deploy

Importante: El script NO configura firewall (IONOS Cloud Panel lo hace), NO hardening SSH, y NO crea .env — eso viene después con ./scripts/vereinsheim setup.

📦 Configuración de entorno — .env y .vereinsheim.local

Antes del despliegue, configura los archivos de entorno:

1. Copia .env.example → .env en el root del repo
2. Genera secrets con ./scripts/vereinsheim setup
3. Configura conexión VPS en .vereinsheim.local:

   # .vereinsheim.local (crear una vez)
   VPS_HOST="tu-dominio.com"
   VPS_REPO_PATH="/home/deploy/vereinsheim"
   DOCKER_USER="deploy"

Generación de secrets:

cd /home/deploy/vereinsheim
./scripts/vereinsheim setup

Este comando interactivo genera todos los secrets necesarios usando openssl rand -base64 32 para passwords y openssl rand -base64 48 para NEXTAUTH_SECRETs.

🐳 Docker Compose — compose.yml

El archivo compose.yml define el stack de producción con:

• Contenedor Caddy como reverse proxy (puertos 80/443)
• Contenedores de aplicación aislados por servicio (Ringwerk:3000, Treffsicher:3000)
• Red Docker interna para comunicación segura
• Volumes para persistencia y backups automáticos
• PostgreSQL compartido con bases de datos separadas por esquema

Inicializar base de datos:

cd /home/deploy/vereinsheim
./scripts/vereinsheim setup db-init

O manualmente:

docker compose -f compose.yml up -d db
docker exec vereinsheim-db psql -U postgres -c "CREATE DATABASE ringwerk; CREATE DATABASE treffsicher;"

🔒 Configuración Caddy — HTTPS automático

El archivo Caddyfile configura reverse proxy con:

• HTTPS automático vía Let's Encrypt (ACME)
• Renovación automática de certificados (90 días)
• Headers de seguridad (HSTS, CSP, X-Frame-Options)
• Cifrado moderno TLS 1.3
• Gzip y Brotli compression

# Caddyfile (en root del repo)
ringwerk.tu-dominio.com {
    encode zstd gzip request_body { max_size 20MB }
    reverse_proxy app-ringwerk:3000
}
treffsicher.tu-dominio.com {
    encode zstd gzip request_body { max_size 20MB }
    reverse_proxy app-treffsicher:3000
}

Para Let's Encrypt staging (tests):

# Descomentar en Caddyfile:
acme_ca https://acme-staging-v02.api.letsencrypt.org/directory

✅ Comprobación posterior

Verifica que todo funcione correctamente:

# Estado de servicios
./scripts/vereinsheim status

# Logs en tiempo real
./scripts/vereinsheim logs

# Migraciones de base de datos
./scripts/vereinsheim migrations ringwerk
./scripts/vereinsheim migrations treffsicher

# Verificar Caddy
curl -I https://ringwerk.tu-dominio.com

Salida esperada:

$ ./scripts/vereinsheim status
✓ caddy: running (port 80,443)
✓ app-ringwerk: running (port 3000)
✓ app-treffsicher: running (port 3000)
✓ db: running (PostgreSQL shared)
✓ backups: /var/backups/vereinsheim
✓ cron: installed (daily backup at 02:00)

💾 Backup y Restore

El CLI interactiva vereinsheim incluye:

• vereinsheim backup: Crea backup manual completo (Postgres dump + uploads)
• vereinsheim deploy: Pre-Backup automático antes de cada despliegue
• vereinsheim restore <app> <dump-file>: Restauración interactiva desde backup
• vereinsheim rollback: Vuelve a versión anterior (usa deploy-history.log)

# Backup manual
./scripts/vereinsheim backup

# Verificar estado de backups
./scripts/vereinsheim status | grep -A 5 backups

# Restaurar desde backup
./scripts/restore.sh ringwerk ~/migration/ringwerk-2026-05-11.dump

El script deploy.sh incluye pre-backup automático antes de cada despliegue, excepto cuando Skip_Backup=1.

🔄 Actualización

Para actualizar a nueva versión:

1. Clona nueva versión del repositorio o pull cambios
2. Ejecuta ./scripts/vereinsheim deploy (incluye pre-backup)
3. Reinicia servicios Docker si es necesario

# Actualización con CLI
./scripts/vereinsheim release

# O manualmente
cd /home/deploy/vereinsheim
git pull origin main
./scripts/vereinsheim deploy

El script deploy.sh limpia imágenes dangling y prune imágenes no usadas >7 días.

⚠️ Errores habituales

• Port 5432 ocupado: Detén Dev-DB con docker compose -f docker-compose.dev.yml stop db
• .env faltante: Ejecuta ./scripts/vereinsheim setup para generar secrets
• Caddy no inicia: Verifica que el dominio esté configurado correctamente en Caddyfile y DNS
• Migraciones fallidas: Revisa logs con vereinsheim logs db
• HTTPS no funciona: Verifica ACME_EMAIL en .env y certificados Let's Encrypt
• PostgreSQL connection refused: Asegúrate de que el contenedor db esté running

🔐 Seguridad

• PostgreSQL compartida pero aislada por usuario/schema (ringwerk_db, treffsicher_db)
• Caddy con HTTPS automático y renovación de certificados Let's Encrypt
• UFW configurado para puertos esenciales (22/80/443) — firewall externa IONOS
• Usuario deploy separado sin acceso root
• Licencia Apache-2.0 — código abierto auditado
• Variables de entorno en archivos .env separados por ambiente (.env, .env.local)
• Secrets gestionados mediante ask_secret() en CLI (no en git)
• Validación de inputs con Prisma ORM para prevenir inyecciones SQL
• NextAuth.js con JWT sessions y password hashing bcrypt

❓ FAQ

Relacionado en HostingByte

Ficha técnica de vereinsheim — Software libre para clubes de tiro deportivo: Ringwerk + Treffsicher · Más guías

Fuentes verificadas

• https://github.com/cykedev/vereinsheim/blob/main/scripts/vereinsheim
• https://software.meyton.info/en/manuals/
• https://github.com/cykedev/vereinsheim/blob/main/.env.example
• https://github.com/cykedev/vereinsheim/blob/main/Caddyfile