Self-hosting

El Vault está diseñado para correr en tu laptop por defecto, pero nada impide que lo ejecutes como servicio compartido en una VPS, en Kubernetes o detrás de tu reverse proxy. Esta página documenta las tres formas oficiales de despliegue.

Docker (recomendado para despliegues compartidos)

docker pull ghcr.io/alcandev/korva-vault:latest
docker compose up -d vault

El Dockerfile es multi-stage:

1. Stage Beacon (Node 22-alpine): construye la SPA React 19 → beacon/dist.
2. Stage Vault (Go 1.26-alpine): copia dist dentro de vault/internal/ui/dist/ y compila con -tags embedui.
3. Stage Runtime (alpine 3.21): corre como korva (uid 1001), volume mount en /data, expone 7437.

Trae un health check cableado:

wget -qO- http://localhost:7437/healthz | grep -q '"status":"ok"' || exit 1

(intervalo 30 s, timeout 5 s, 3 reintentos, periodo de inicio 10 s).

Docker Compose

El repo incluye docker-compose.yml con dos servicios:

services:
  vault:
    image: ghcr.io/alcandev/korva-vault:latest
    ports: ["7437:7437"]
    volumes:
      - korva-data:/data
      - ${KORVA_ADMIN_KEY_PATH}:/data/admin.key:ro
  # Traefik opcional para HTTPS automático vía Let's Encrypt
  # traefik:
  #   ...
volumes:
  korva-data:

Para correr solo el vault:

docker compose up -d vault

Para correr vault + el servidor de licencias (solo operadores, perfil teams):

KORVA_LICENSING_SECRET=change-me \
KORVA_LICENSING_KEY_PEM="$(cat priv.pem)" \
  docker compose --profile teams up -d

Traefik para HTTPS automático

El docker-compose.yml viene con los labels de Traefik comentados. Descoméntalos para exponer el Vault en vault.tuempresa.com con certificados Let’s Encrypt que se auto-renuevan:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.vault.rule=Host(`vault.tuempresa.com`)"
  - "traefik.http.routers.vault.entrypoints=websecure"
  - "traefik.http.routers.vault.tls.certresolver=letsencrypt"
  - "traefik.http.services.vault.loadbalancer.server.port=7437"

Los clientes apuntan al host público:

KORVA_VAULT_HOST=vault.tuempresa.com korva ...

LaunchAgent en macOS (máquinas de desarrollo)

cp scripts/korva-vault.plist ~/Library/LaunchAgents/dev.korva.vault.plist
launchctl load ~/Library/LaunchAgents/dev.korva.vault.plist

• Label: dev.korva.vault
• RunAtLoad, KeepAlive ante caída
• Logs en ~/.korva/logs/vault.{log,error.log}
• Throttle de reinicio: 10 s

Servicio user de systemd (servidores Linux)

mkdir -p ~/.config/systemd/user
cp scripts/korva-vault.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now korva-vault

• Restart on-failure (delay 5 s), máx. 5 reinicios en 60 s
• Logs vía journald: journalctl --user -u korva-vault -f
• Hardening: NoNewPrivileges, PrivateTmp, ProtectSystem=strict, ProtectHome=read-only, ReadWritePaths=~/.korva

Variables de entorno necesarias

Consideraciones de reverse proxy

El Vault espera que TLS se termine en el proxy y recibir HTTP/1.1 en cleartext internamente. CORS se configura vía KORVA_CORS_ORIGIN. El rate limit (120 req/min/IP) se aplica dentro del Vault, así que no necesitas una regla de WAF separada para protegerlo.

Observabilidad

• Sonda de salud: GET /healthz devuelve {"status":"ok"}.
• Snapshot de estado: GET /api/v1/status — versión, uptime, tier de licencia, total de observaciones.
• Métricas: GET /api/v1/metrics — formato Prometheus.

Conéctalas a tu stack de monitoring.

Dónde viven los datos en Docker

El volumen nombrado korva-data se mapea a /data dentro del contenedor:

Toma un snapshot del volumen diariamente para backup; SQLite soporta backups en caliente si usas VACUUM INTO.

Siguiente

• API REST pública
• Administración de Teams
• Solución de problemas