Guía operativa saneada · Verificada el 3 de septiembre de 2026 · America/Santiago

Docker detrás de Nginx

Convención para ordenar, replicar y publicar aplicaciones Docker sin exponer bases de datos ni secretos.

Modelo vigente

Internet → UFW → Nginx
                    ├── /       → Moodle → PHP-FPM → PostgreSQL host
                    ├── som.minayao.site → SOM → PostgreSQL privado
                    ├── locker.minayao.site → Learning Locker → MongoDB/Redis
                    ├── yet.minayao.site → Yet SQL LRS → PostgreSQL privado
                    ├── kuma.minayao.site → Kuma Docker
                    └── portainer.minayao.site → Portainer Docker

Ollama → 127.0.0.1:11434 del host, sin exposición pública

Nginx termina TLS. Cada backend Docker publica únicamente en 127.0.0.1; las bases permanecen en redes internas sin puertos del host.

Orden recomendado

/opt/apps/<proyecto>/
├── .git/
├── README.md
├── Dockerfile
├── compose.yaml
├── compose.prod.yaml
├── .env.example
├── .env.prod          # secreto local, chmod 600, fuera de Git
├── config/
├── scripts/
└── nginx/
    └── <proyecto>.conf.example

SOM permanece por ahora en /opt/backendsom/app. Learning Locker y Yet SQL LRS están en /opt/docker-projects/locker y /opt/docker-projects/yet. Los tres tienen Compose reproducible. No deben moverse sin respaldar y comprobar nombres de proyecto, redes y volúmenes.

Zona	Uso
`/opt/apps`	Repositorios y Compose de nuevas aplicaciones Docker.
`/opt/docker-projects/locker`	Compose de Learning Locker.
`/opt/docker-projects/yet`	Compose de Yet SQL LRS.
`/opt/server-architecture`	Inventario publicado en `doc.minayao.site` y `/arqui/`.
`/var/www/moodle`	Moodle tradicional, fuera de Docker.
`/var/lib/docker`	Estado administrado por Docker; nunca repositorios manuales.

Tipos de despliegue

Tipo	Componentes y controles
Web simple	Aplicación, healthcheck, loopback y proxy Nginx.
Stack como SOM	Web + base/caché privada + volúmenes + redes internal/egress + migraciones y backup.
Plataforma como Kuma	Volumen dedicado, WebSocket si corresponde, imagen fijada y exportación de configuración.
Administración como Portainer	Socket Docker, acceso restringido, autenticación fuerte y respaldo. Equivale a control del host Docker.

Procedimiento de alta

Asignar nombre, URL, puerto loopback y responsable.
Clonar en /opt/apps/<proyecto> y revisar Dockerfile/Compose.
Crear .env.prod desde el ejemplo, fuera de Git y con permisos 600.
Validar Compose sin publicar valores sensibles.
Construir o descargar imágenes de versiones aprobadas.
Levantar el stack y comprobar salud, redes, volúmenes y puertos.
Probar directamente el backend por loopback.
Instalar el snippet Nginx, validar con nginx -t y recargar.
Probar HTTPS, autenticación, estáticos, cargas y WebSockets.
Agregar monitorización, backup/restore y registro en la arquitectura.

Ajuste Nginx por subruta

location = /ejemplo {
    return 301 /ejemplo/;
}
location ^~ /ejemplo/ {
    proxy_pass http://127.0.0.1:8100;
    proxy_http_version 1.1;
    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;
}

La aplicación debe soportar el prefijo. Si asume vivir en /, usar un nombre DNS separado. Los puertos HTTPS adicionales quedan reservados para casos justificados y requieren UFW y TLS.

Replicar desde Git

git clone <repositorio> /opt/apps/<proyecto>
cd /opt/apps/<proyecto>
cp .env.example .env.prod
chmod 600 .env.prod
# completar secretos por un canal seguro
docker compose --env-file .env.prod -f compose.prod.yaml config --quiet
docker compose --env-file .env.prod -f compose.prod.yaml pull
docker compose --env-file .env.prod -f compose.prod.yaml build --pull
docker compose --env-file .env.prod -f compose.prod.yaml up -d
docker compose --env-file .env.prod -f compose.prod.yaml ps

Nginx se integra explícitamente desde el host: el repositorio aporta un ejemplo, pero no debe poder reemplazar automáticamente la configuración frontal.

Checklist

Compose, Dockerfile, migraciones y healthchecks versionados.
Secretos fuera de Git y separados por servicio.
Aplicación en loopback; bases/cachés sólo en red interna.
Volúmenes identificables, backup restaurable y rollback documentado.
Versiones o digests fijados; evitar latest.
Nginx, HTTPS, UFW, monitorización y logs comprobados.

La plantilla Compose completa, reglas de actualización, variantes de publicación y pendientes actuales están en el documento Markdown.