Primeros pasos con Docker Compose

El repositorio incluye un stack Compose bajo deploy/compose/: un despliegue endurecido de nodo único (SQLite embebido, cero dependencias externas) más dos overlays — un override multi-tenant con Postgres y un perfil de copia de seguridad para recuperación ante desastres. Este tutorial te lleva desde up -d hasta un control plane configurado con copias de seguridad.

El contenedor envuelve el mismo binario único que cualquier otra instalación; solo difiere el empaquetado. Los comandos de abajo son los propios puntos de entrada documentados del stack (deploy/compose/*.yml), y el flujo de primer arranque que conducen es el mismo que se verifica de extremo a extremo contra el binario en el tutorial de nodo único.

Olivares 0.4

La próxima release es 0.4; todavía no está publicada en GitHub. Los comandos siguientes describen los artefactos previstos. Compila desde el código fuente hasta su publicación y verifica cada artefacto antes de usarlo. El estado observado está en docs/releases/0.4-install-surfaces.json.

1. Levanta el stack de nodo único (SQLite)

1. Arráncalo:

   En hosts donde AppArmor controla la creación de espacios de nombres de usuario, completa “Session confinement on AppArmor hosts” en deploy/compose/README.md en el host del daemon de Docker antes de iniciar la pila.

   docker compose -f deploy/compose/docker-compose.yml up --wait --wait-timeout 120

   Lo que obtienes, por diseño:

   Propiedad	Valor
   Puertos	8443 (HTTPS: REST + UI web), 8444 (gRPC) — publicados en todas las interfaces del host, porque esto es un servidor. Pon OLIVARES_BIND=127.0.0.1 en .env para restringirlos al host
   Datos	volumen nombrado olivares-data → /var/lib/olivares (almacén SQLite, clave de firma de auditoría, material TLS)
   Endurecimiento	corre como 65532:65532, root de solo lectura, todas las capabilities descartadas, no-new-privileges, tmpfs /tmp
   Healthcheck	ejecución directa de olivares readyz dentro del binario — sin shell, curl ni wget. Sólo un HTTP 200 de /readyz local es saludable

2. Pregunta al motor dónde está, y lee el token de configuración de un solo uso de los logs:

   # where the console answers, and whether setup is still pending. It runs the binary
   # directly and needs no shell.
   docker compose -f deploy/compose/docker-compose.yml exec olivares olivares first-boot
   
   # the one-time setup token, printed once at first boot
   docker compose -f deploy/compose/docker-compose.yml logs olivares \
     | sed -n '/FIRST-BOOT SETUP/,/========================/p'

3. Crea el primer administrador, inicia sesión, y crea tu organización — exactamente como en el tutorial de nodo único (la API es la misma; el certificado TLS es autofirmado en el primer arranque, así que curl -k para el bootstrap):

   curl -ksf -X POST https://localhost:8443/v1/setup \
     -H 'Content-Type: application/json' \
     -d '{"token":"<olst_ token>","email":"you@example.com","password":"<strong-password>"}'

Contrato actual y cualificación en el host

Contrato de disponibilidad de Compose. Las fixtures locales herméticas de HTTP/TLS prueban las tres respuestas de la sonda: 200 → rc 0, una respuesta no-200 → rc 1, y un fallo de entrada/TLS/transporte → rc 2. La cualificación Docker sigue sin medirse hasta que el workflow de dispatch termine correctamente para este commit; un workflow guardado no es evidencia de que se ejecutó.

¿Te perdiste el token?

Un reinicio no lo vuelve a imprimir (solo se almacena su hash). Mientras no exista ningún administrador, acuña uno de repuesto sin reiniciar nada — el motor en marcha lo acepta al instante y el token anterior deja de funcionar:

docker compose -f deploy/compose/docker-compose.yml exec olivares \
  olivares first-boot --new-token

Los cuatro comandos, y por qué cada uno necesita el `-f`

El stack nombra su propio proyecto de Compose, así que el contenedor del motor es olivares (no compose-olivares-1) y los servicios de los overrides son olivares-postgres-1 y olivares-backup-1. Compose sigue buscando un fichero compose en el directorio de trabajo, y éste vive en deploy/compose/ — así que un docker compose ps a secas en la raíz del repositorio responde “no configuration file provided”. Pasa -f siempre, o haz export COMPOSE_FILE=deploy/compose/docker-compose.yml una vez.

docker compose -f deploy/compose/docker-compose.yml exec olivares olivares first-boot
docker compose -f deploy/compose/docker-compose.yml logs olivares
docker compose -f deploy/compose/docker-compose.yml ps
docker compose -f deploy/compose/docker-compose.yml down

olivares quickstart es la vía del binario local, no ésta: aquí el servidor ya está corriendo — el comando del contenedor es serve — y quickstart arrancaría un segundo motor dentro del contenedor.

2. Cablea fuentes

Las fuentes se declaran en un único fichero de operador nombrado por OLIVARES_SOURCES_CONFIG (conectar una fuente). Para el contenedor, monta el fichero y establece la variable con un pequeño override:

# deploy/compose/docker-compose.sources.yml (yours — not shipped)
services:
  olivares:
    environment:
      OLIVARES_SOURCES_CONFIG: /etc/olivares/sources.json
    volumes:
      - ./sources.json:/etc/olivares/sources.json:ro

docker compose -f deploy/compose/docker-compose.yml \
               -f deploy/compose/docker-compose.sources.yml up -d
docker compose -f deploy/compose/docker-compose.yml logs olivares | grep "ingest: wired source"

Recuerda que las rutas dentro de sources.json son rutas de contenedor — un tail de log pgAudit, por ejemplo, necesita que el directorio de logs de Postgres también esté montado de solo lectura dentro del contenedor.

3. Copias de seguridad DR cifradas (el perfil backup)

El stack incluye un servicio de copia de seguridad de un solo disparo que produce un bundle cifrado y con continuidad de ledger segura (olivares dr backup):

Guarda la passphrase en un archivo privado fuera del repositorio y de la imagen, y conserva una copia en un lugar seguro fuera de este host: sin ella no se puede restaurar ningún bundle. Dale al contenedor de backup acceso de solo lectura (la imagen se ejecuta con el UID 65532):

sudo install -d -o 65532 -g 65532 -m 0700 /srv/olivares-dr
sudo install -o 65532 -g 65532 -m 0400 /path/to/private-passphrase /srv/olivares-dr/dr-pass

BACKUP_TS="$(date -u +%Y%m%dT%H%M%SZ)" \
docker compose -f deploy/compose/docker-compose.yml \
               -f deploy/compose/docker-compose.backup.yml \
               -f - --profile backup run --rm backup <<'YAML'
services:
  backup:
    volumes:
      - /srv/olivares-dr/dr-pass:/run/secrets/dr-pass:ro
YAML

Envuelve ese comando en el cron del host para un RPO programado, y espeja el volumen olivares-backups offsite — una copia de seguridad en el mismo host no es recuperación ante desastres, y la passphrase debe viajar por separado de los bundles (3-2-1). El procedimiento completo, incluyendo el simulacro de restauración (olivares dr verify), está en copia de seguridad y restauración.

4. Opcional: el override multi-tenant con Postgres

Para la topología multi-tenant, superpón el override de Postgres. Levanta un Postgres 16, aprovisiona el rol de mínimo privilegio olivares_app (sin superuser, sin BYPASSRLS — el motor se niega a arrancar contra un rol privilegiado, porque la seguridad a nivel de fila es el backstop del tenant), y apunta el motor a él:

El override también aprovisiona olivares_admin, un rol separado con NOSUPERUSER BYPASSRLS y acceso de solo lectura a las tablas del motor. El motor lo usa mediante --admin-dsn para lecturas entre tenants, incluida la configuración inicial.

Fija primero tres contraseñas distintas, usando solo A-Z a-z 0-9 . _ ~ - para esta demo de Compose, y luego levanta el stack:

cp deploy/compose/.env.example deploy/compose/.env
# set three distinct passwords in deploy/compose/.env:
# POSTGRES_SUPERUSER_PASSWORD, OLIVARES_DB_PASSWORD, OLIVARES_ADMIN_PASSWORD

docker compose -f deploy/compose/docker-compose.yml \
               -f deploy/compose/docker-compose.postgres.yml up -d

El Postgres de compose es una topología de demostración

El override conecta con sslmode=disable dentro de la red de compose — correcto para evaluación, no para producción. Un despliegue de Postgres de producción usa TLS con sslmode=verify-full y un secreto DSN — esa es la vía de Kubernetes/Helm.

Salud

curl -ks https://localhost:8443/readyz
# {"leader":true,"setup_required":false,"status":"ok","store":"up"}
curl -ks https://localhost:8443/metrics | grep olivares_store_up

Próximos pasos

• Cablea señales reales: las guías de conectores.
• Programa y ensaya copias de seguridad: copia de seguridad y restauración.
• Monitorízalo: métricas de Prometheus, SLOs y alertas.
• ¿Pasando a multi-nodo? Kubernetes con Helm, incluyendo HA y el DaemonSet de colectores.