Cómo instalar Infisical con Docker Compose y pasar secretos a tus contenedores

Infisical es una plataforma de gestión de secretos de código abierto que se instala con Docker Compose en tres contenedores (backend, PostgreSQL y Redis) y entrega los secretos de cada entorno a tus servicios mediante su CLI. La instalé el 7 de octubre de 2026 con la versión v0.166.2, creé un proyecto con entornos, guardé secretos y un contenedor de Python leyó su clave con infisical run. Aquí tienes el paso a paso con lo que ejecuté, qué incluye la edición sin licencia y cuándo elegir OpenBao o Docker en su lugar. También tienes la versión en inglés.

Puntos clave

• Infisical v0.166.2 arranca con el docker-compose.prod.yml del repositorio: backend, PostgreSQL y Redis. En mi prueba, el backend usó 687,5 MiB de RAM, PostgreSQL 149 MiB y Redis 12 MiB.
• La imagen infisical/infisical:v0.166.2 ocupa 2,74 GB en disco. El repositorio tiene 29 640 estrellas en GitHub.
• Sin licencia, mi instancia tenía activos 4 de los 57 indicadores booleanos del plan. Proyectos, entornos, identidades y miembros no tenían límite.
• Quedan fuera funciones como secretos dinámicos, rotación, aprobaciones, SAML y registro de auditoría. Las notas de licencia^[1] lo resumen así: "While most features in Infisical are free to use, others are paid and require purchasing an enterprise license to use them."
• Un contenedor de Python recibió NOTES_API_KEY a través de infisical run, y docker inspect no muestra ese valor.

Qué es Infisical y qué piezas lleva

Infisical guarda secretos cifrados en PostgreSQL, los agrupa en proyectos con entornos (desarrollo, preproducción y producción por defecto) y los sirve a personas y a máquinas con control de acceso. Redis se usa para la caché y las colas. El código fuera de los directorios ee/ está bajo licencia MIT, y lo que hay dentro de ee/ tiene licencia propia, según el fichero LICENSE del repositorio^[2].

La documentación de Docker Compose avisa de que es una configuración para pruebas y despliegues pequeños, sin alta disponibilidad. Pide como mínimo 2 núcleos, 4 GB de RAM y 20 GB de disco. Para algo mayor, su guía de Kubernetes^[3] es el camino que recomiendan.

Cómo instalar Infisical con Docker Compose

Partí del docker-compose.prod.yml oficial con tres cambios: fijé la imagen a v0.166.2 en lugar de latest, usé postgres:16-alpine y redis:8-alpine, y publiqué el puerto en 29700. El archivo oficial usa postgres:14-alpine; con la 16 no tuve ningún problema. Docker Engine era el 29.5.2 y Compose el 2.40.3.

services:
  backend:
    image: infisical/infisical:v0.166.2
    depends_on:
      db: {condition: service_healthy}
      redis: {condition: service_started}
    env_file: .env
    ports: ["29700:8080"]
    environment: [NODE_ENV=production]
    restart: unless-stopped
  redis:
    image: redis:8-alpine
    volumes: [redis_data:/data]
  db:
    image: postgres:16-alpine
    env_file: .env
    volumes: [pg_data:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U infisical"]
      interval: 5s
      retries: 10
volumes: {pg_data: {}, redis_data: {}}

El .env lleva la clave de cifrado, el secreto de autenticación y las credenciales de la base de datos. No uses los valores de ejemplo del repositorio: genéralos tú.

PGPASS=$(openssl rand -hex 12)
cat > .env <<EOF
ENCRYPTION_KEY=$(openssl rand -hex 16)
AUTH_SECRET=$(openssl rand -base64 32)
POSTGRES_USER=infisical
POSTGRES_PASSWORD=$PGPASS
POSTGRES_DB=infisical
DB_CONNECTION_URI=postgres://infisical:$PGPASS@db:5432/infisical
REDIS_URL=redis://redis:6379
SITE_URL=http://localhost:29700
HTTPS_ENABLED=false
EOF
docker compose up -d

Guarda ENCRYPTION_KEY fuera del servidor: sin ella, una copia de la base de datos no sirve de nada. HTTPS_ENABLED=false solo es válido para probar en localhost; las preguntas frecuentes de autoalojamiento^[4] explican que sin HTTPS las cookies seguras no se guardan y la sesión se pierde al recargar. Detrás de un proxy inverso con TLS, quítalo.

Cuando el backend termina de migrar la base de datos, /api/status devuelve 200 y el registro del contenedor muestra la dirección de alta del administrador:

Welcome to Infisical

Create your Infisical administrator account at:
http://localhost:29700/admin/signup

El primer usuario que se registra queda como superadministrador. Lo hice por el navegador. Pide nombre, correo y una contraseña de al menos 14 caracteres, después el nombre de la organización (Jacar Demo) y por último la política de altas, que por defecto es solo por invitación. Arriba verás el aviso de que no hay SMTP configurado: sin correo no puedes invitar usuarios por email, y para esta prueba da igual.

Crear un proyecto, entornos y secretos

En Secrets Management creé el proyecto Notes API. Infisical lo crea con tres entornos, Development, Staging y Production, y el menú de entornos permite añadir más con "Add Environment". Para cargar secretos usé Paste Secrets, que acepta formato .env, JSON o YAML:

# Development
NOTES_API_KEY=dev-7f3c1a9e
NOTES_DB_PASSWORD=dev-only-password

# Production
NOTES_API_KEY=prod-b21d90c4
NOTES_DB_PASSWORD=prod-only-password

Son valores de prueba. Comprobé que Infisical los cifra antes de guardarlos: volqué la base de datos con pg_dump, 3 371 132 bytes, y no apareció ninguna de las dos claves en claro. La interfaz mantiene un historial de versiones de cada secreto, que en mi instancia sin licencia seguía activo (secretVersioning: true).

Crear una identidad de máquina para el contenedor

Un contenedor no debe entrar con tu usuario. Infisical usa identidades de máquina, y el método más directo es Universal Auth, que da un identificador de cliente y un secreto de cliente. Los pasos en la interfaz son:

1. En Access Control, pestaña Machine Identities, crea notes-api-container. Universal Auth ya viene añadido.
2. En Add to Project, asígnala al proyecto Notes API con el rol Viewer, que es solo lectura.
3. En View Auth Method, copia el Client ID y pulsa Add Client Secret. El secreto se muestra una sola vez.

Probé que Viewer es de verdad solo lectura: un infisical secrets set con esa identidad devolvió 403 You are not allowed to create on secrets. Pero hay una limitación: el rol vale para todo el proyecto, así que la misma identidad también leyó los secretos de Production. Separar entornos por identidad exige roles personalizados, que no están en la edición sin licencia (rbac: false en mi instancia). La alternativa gratuita es un proyecto distinto por entorno.

Inyectar los secretos con infisical run

La CLI de Infisical (v0.43.139, publicada el 5 de octubre de 2026) es un único binario de Go de unos 150 MB. Primero la probé fuera de Docker: infisical login con Universal Auth devuelve un token de acceso, y infisical run lo usa para lanzar un proceso con los secretos como variables de entorno.

T=$(infisical login --method=universal-auth \
  --client-id=$CLIENT_ID --client-secret=$CLIENT_SECRET \
  --domain=http://localhost:29700 --plain --silent)

for e in dev staging prod; do
  infisical run --domain=http://localhost:29700 \
    --projectId=$PROJECT_ID --env=$e --token="$T" -- \
    sh -c 'echo "key=$NOTES_API_KEY"'
done

La salida fue key=dev-7f3c1a9e en dev, vacía en staging (con el aviso "Injecting 0 Infisical secrets") y key=prod-b21d90c4 en prod. Los entornos son los slugs dev, staging y prod, no los nombres que ves en pantalla.

Una app real en un contenedor

Para un caso completo escribí una app de Python que lee NOTES_API_KEY y responde por HTTP. El contenedor monta el binario de la CLI de solo lectura y arranca con un start.sh que inicia sesión y delega en infisical run:

#!/bin/sh
set -e
TOKEN=$(infisical login --method=universal-auth \
  --client-id="$INFISICAL_CLIENT_ID" --client-secret="$INFISICAL_CLIENT_SECRET" \
  --plain --silent)
exec infisical run --token="$TOKEN" --projectId="$INFISICAL_PROJECT_ID" \
  --env="${APP_ENV:-dev}" -- python /app/app.py

  notes:
    image: python:3.13-alpine
    depends_on: [backend]
    env_file: demo.env        # INFISICAL_CLIENT_ID, _CLIENT_SECRET, _PROJECT_ID, _DOMAIN
    environment: ["APP_ENV=${APP_ENV:-dev}"]
    volumes:
      - ./cli/infisical:/usr/local/bin/infisical:ro
      - ./app:/app:ro
    ports: ["29701:8000"]
    command: ["/app/start.sh"]

INFISICAL_DOMAIN apunta al servicio por su nombre en la red de Compose (http://backend:8080). Con APP_ENV=dev, curl localhost:29701 respondió NOTES_API_KEY loaded: True, 12 chars, starts with 'dev-'. Al recrear el contenedor con APP_ENV=prod respondió 13 caracteres y el prefijo prod. El mismo contenedor, sin cambiar la imagen, lee un valor distinto según el entorno.

Lo que más me interesaba era dónde acaba el secreto. docker inspect solo muestra las credenciales de arranque (identificador, secreto de cliente y proyecto), y un docker exec ... env no encuentra ninguna variable NOTES_. El proceso hijo de Python sí tiene las dos. Dicho con cuidado: el valor deja de estar en el fichero Compose y en docker inspect. Pero el secreto de cliente de Universal Auth sigue en el entorno del contenedor, y quien lo robe puede leer todo lo que la identidad ve. Por eso conviene el rol de solo lectura y, cuando puedas, un límite de IP.

La CLI también tiene --watch, que reinicia la aplicación cuando cambian los secretos (consulta cada 10 s por defecto, según la ayuda de infisical run^[5]). No lo probé.

Alternativa: el agente de Infisical y un fichero .env

Si no quieres envolver el proceso, el agente (infisical agent) renderiza los secretos en un fichero a partir de una plantilla. Es útil para aplicaciones que solo saben leer un .env. La configuración es esta:

infisical:
  address: "http://backend:8080"
auth:
  type: "universal-auth"
  config:
    client-id: "/agent/client-id"
    client-secret: "/agent/client-secret"
    remove_client_secret_on_read: false
templates:
  - source-path: /agent/notes.tmpl
    destination-path: /secrets/notes.env
    config:
      polling-interval: 60s

La plantilla usa la función listSecrets del agente^[6] con el identificador del proyecto, el entorno y la ruta. Mi primer intento con polling-interval: 10s falló con polling interval must be at least 60 seconds, así que 60 s es el mínimo. Con ese valor, el agente escribió /secrets/notes.env con las dos variables a los pocos segundos de arrancar. Otro contenedor puede leer ese fichero desde un volumen compartido con env_file o con un source.

Qué incluye la edición gratuita y qué es de pago

La página de precios^[7] separa las funciones por plan en la nube. Free incluye 5 identidades, Pro suma rotación de secretos y SAML, Advanced añade secretos dinámicos y roles personalizados, y Enterprise trae flujos de aprobación, LDAP y SCIM. Para una instancia propia, esos límites de identidades no se aplican sin licencia, y lo más fiable es preguntarle a tu propio servidor. Consulté el endpoint del plan de la organización y devolvió esto:

Para activar las funciones de pago, la documentación^[1] indica que hay que comprar una licencia, poner la clave en la variable LICENSE_KEY y permitir que la instancia valide la clave contra el servidor de licencias. Si la licencia caduca, Infisical sigue funcionando y solo se desactivan las funciones de pago. Antes de decidir, verifica en esa página y en la de precios qué cubre cada plan en el momento en que lo despliegues, porque la oferta cambia.

Cuándo elegir Infisical, OpenBao o Docker secrets

Docker Compose resuelve el caso mínimo sin instalar nada, y su documentación de secretos^[8] monta cada secreto como fichero en /run/secrets. Infisical añade la parte que ahí falta: una interfaz, entornos, un historial y acceso por identidad. OpenBao va más lejos en operación (hay que inicializarlo y desellarlo) y es lo que debes mirar si necesitas credenciales dinámicas sin pagar licencia. Infisical cobra los secretos dinámicos en la nube y en la edición Advanced.

Preguntas frecuentes

¿Infisical es gratis para autoalojar?

El núcleo es de código abierto y su documentación dice que "most features in Infisical are free to use". En mi instancia sin licencia no había límite de proyectos, entornos ni identidades. Rotación, secretos dinámicos, SAML y roles personalizados requieren una licencia de pago.

¿Puedo usar Infisical con Docker Compose sin cambiar mi aplicación?

Sí. infisical run -- tu-comando inyecta los secretos como variables de entorno, así que la aplicación no cambia. Si solo lee un fichero .env, usa el agente con una plantilla.

¿Es seguro dejar el secreto de cliente en el contenedor?

Es el punto débil del esquema. Los secretos reales no aparecen en docker inspect, pero el secreto de Universal Auth sí. Dale a la identidad el rol Viewer, limita las IP de confianza y rótalo si sale del servidor.

Conclusión

Infisical se instala en unos minutos con Docker Compose y cumple lo que promete: un proyecto, tres entornos y un contenedor que recibe su clave sin que el valor viva en el fichero Compose. En mi prueba, la edición sin licencia fue suficiente para este flujo, y se queda corta en roles por entorno, rotación y auditoría.

Si empiezas hoy, fija la versión de la imagen, guarda ENCRYPTION_KEY aparte y usa un proyecto distinto para producción. Cuando necesites credenciales dinámicas, compara con OpenBao antes de pagar una licencia.

Fuentes: [1] Repositorio de Infisical en GitHub^[2], [2] Versión v0.166.2^[9], [3] Versión v0.43.139 de la CLI^[10], [4] Infisical Enterprise (licencia)^[1], [5] Docker Compose en la documentación de Infisical^[11], [6] Infisical Agent^[6], [7] Precios de Infisical^[7], [8] Imagen infisical/infisical en Docker Hub^[12], [9] Secretos en Docker Compose^[8].

Fuentes

1. notas de licencia
2. fichero LICENSE del repositorio
3. su guía de Kubernetes
4. preguntas frecuentes de autoalojamiento
5. ayuda de infisical run
6. agente
7. página de precios
8. documentación de secretos
9. Versión v0.166.2
10. Versión v0.43.139 de la CLI
11. Docker Compose en la documentación de Infisical
12. Imagen infisical/infisical en Docker Hub