Infisical Docker Compose: Gestiona Secretos de Equipo 2026

Con Infisical Docker Compose montas un gestor de secretos para tu equipo: claves de API, contraseñas de base de datos y tokens dejan de vivir en ficheros .env repartidos por portátiles y pasan a un sitio con control de acceso, versionado y registro de quién consulta qué.

Es la alternativa libre a Doppler y una opción bastante más manejable que HashiCorp Vault cuando lo que necesitas es gestionar secretos de aplicación, no montar una infraestructura de identidad completa.

Qué problema resuelve Infisical Docker Compose

El escenario que resuelve Infisical Docker Compose es reconocible en cualquier equipo pequeño. El fichero .env de producción circula por chat, alguien lo tiene desactualizado, nadie sabe con certeza qué claves siguen activas y cuando se va una persona no hay forma razonable de rotar lo que tocó.

Un gestor de secretos rompe ese ciclo con cuatro propiedades que un fichero no puede dar.

• Fuente única. El valor vive en un sitio y se consulta desde ahí, no se copia.
• Permisos por persona y entorno. Que alguien vea desarrollo no implica que vea producción.
• Historial. Cada cambio queda registrado y se puede volver atrás.
• Auditoría. Sabes quién consultó qué secreto y cuándo.

Conviene distinguirlo de un gestor de contraseñas personal. Vaultwarden guarda las credenciales que usan las personas en su navegador; esto guarda las que consumen las aplicaciones en tiempo de ejecución. Son problemas distintos y ambas piezas conviven bien.

Requisitos previos de Infisical Docker Compose

La pila de Infisical Docker Compose son tres contenedores: la aplicación, PostgreSQL para los datos y Redis para caché y colas. Nada exótico, y bastante ligero comparado con otras herramientas del mismo ámbito.

Instalar Infisical Docker Compose paso a paso

Paso 1: generar las claves criptográficas

Este es el paso más importante de Infisical Docker Compose y tiene un detalle técnico que no se puede improvisar: cada clave tiene un formato y una longitud concretos.

mkdir -p ~/infisical && cd ~/infisical

echo "ENCRYPTION_KEY=$(openssl rand -hex 16)"    >  .env
echo "AUTH_SECRET=$(openssl rand -base64 32)"    >> .env
echo "POSTGRES_USER=infisical"                   >> .env
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" >> .env
echo "POSTGRES_DB=infisical"                     >> .env
echo "SITE_URL=https://secretos.midominio.es"    >> .env

chmod 600 .env

Fíjate en los formatos: la clave de cifrado es hexadecimal de 16 bytes, y el secreto de autenticación es base64 de 32 bytes. No son intercambiables, y usar el formato equivocado da errores de arranque poco descriptivos.

Paso 2: escribir el docker-compose.yml

services:
  infisical:
    image: infisical/infisical:latest-postgres
    container_name: infisical
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    environment:
      - NODE_ENV=production
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - AUTH_SECRET=${AUTH_SECRET}
      - DB_CONNECTION_URI=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
      - REDIS_URL=redis://redis:6379
      - SITE_URL=${SITE_URL}
    ports:
      - "8080:8080"

  db:
    image: postgres:16-alpine
    container_name: infisical-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    container_name: infisical-redis
    restart: unless-stopped
    volumes:
      - ./redis:/data

Levanta la pila de Infisical Docker Compose y revisa que la aplicación aplica sus migraciones sin errores.

docker compose up -d
docker compose logs -f infisical

Paso 3: publicar con HTTPS y crear la organización

El valor de SITE_URL debe coincidir con la dirección pública definitiva. Es lo que usan los enlaces de invitación y el flujo de inicio de sesión, así que ponlo bien antes de dar de alta a nadie. Con Traefik y certificados automáticos lo resuelves con etiquetas.

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.infisical.rule=Host(`secretos.midominio.es`)"
      - "traefik.http.routers.infisical.entrypoints=websecure"
      - "traefik.http.routers.infisical.tls.certresolver=letsencrypt"
      - "traefik.http.services.infisical.loadbalancer.server.port=8080"

El primer usuario que se registre será el administrador de la organización. Hazlo tú de inmediato y después restringe el registro abierto, o cualquiera que llegue a la URL podrá crearse una cuenta.

Organizar proyectos y entornos en Infisical Docker Compose

La estructura de Infisical Docker Compose es sencilla y conviene respetarla desde el principio: una organización contiene proyectos, y cada proyecto tiene entornos con rutas jerárquicas dentro.

tienda-online/
├── development/
│   ├── /              DATABASE_URL, REDIS_URL
│   └── /pasarela      STRIPE_KEY
├── staging/
└── production/
    ├── /              DATABASE_URL, REDIS_URL
    └── /pasarela      STRIPE_KEY

Esa separación por entorno es la que da valor real: el equipo de desarrollo puede tener acceso completo a development y ninguno a production, con las mismas claves nombradas igual en ambos sitios. La aplicación no cambia, solo cambia de dónde lee.

Las rutas dentro de cada entorno funcionan como carpetas y sirven para dos cosas. La primera es organizativa, agrupando por servicio o por componente cuando el proyecto crece. La segunda es de permisos: puedes dar acceso a una ruta concreta sin abrir el entorno entero, que es justo lo que necesitas cuando un colaborador externo solo debe tocar la integración de la pasarela de pago y nada más.

Una convención que ahorra discusiones: nombra las claves igual en todos los entornos y no metas el entorno en el nombre. Nada de DATABASE_URL_PROD; la separación ya la da el entorno, y duplicar esa información en el nombre acaba provocando que alguien lea la variable equivocada.

Consumir secretos de Infisical Docker Compose sin ficheros

Aquí está el cambio de mentalidad que trae Infisical Docker Compose. En lugar de escribir un .env, la herramienta de línea de comandos inyecta las variables directamente en el proceso.

infisical login --domain https://secretos.midominio.es
infisical init

infisical run --env=development -- npm start
infisical run --env=production -- ./mi-aplicacion

El proceso hijo recibe las variables en memoria y nunca se escribe nada en disco. Si alguien inspecciona el repositorio o el servidor, no encuentra credenciales porque sencillamente no están ahí.

Ese cambio tiene un efecto secundario que se agradece mucho en el día a día: dar de alta a alguien nuevo deja de ser un ritual. En lugar de pasarle ficheros por chat y explicarle cuáles van en cada entorno, le das acceso al proyecto y arranca la aplicación con un comando. Todo lo que necesita ya está donde tiene que estar, con los permisos que le corresponden.

Si prefieres no cambiar cómo arrancan tus servicios, también puedes generar el fichero desde la herramienta y seguir usándolo como siempre. Es un paso intermedio razonable durante la migración, aunque pierdes buena parte de la ventaja: el fichero vuelve a estar en disco y vuelve a poder quedarse obsoleto.

infisical export --env=development > .env

Mi recomendación es usarlo solo mientras adaptas los despliegues, y ponerte como objetivo eliminar ese comando del flujo en cuanto puedas.

Para automatismos no puedes usar credenciales de persona. Ahí entran las identidades de máquina, que se autentican con un identificador y un secreto de cliente y tienen sus propios permisos.

  - name: desplegar
    image: infisical/cli:latest
    environment:
      INFISICAL_TOKEN:
        from_secret: infisical_token
    commands:
      - infisical run --env=production --projectId=$PROJECT_ID -- ./deploy.sh

Ese fragmento encaja en el servidor de integración continua con Woodpecker que montamos hace unos días, y el mismo patrón vale para cualquier otro sistema de pipelines.

Permisos, auditoría y rotación

Estas tres funciones son las que separan un gestor de secretos de una carpeta compartida bien ordenada, y merece la pena configurarlas pronto.

Quién ve qué

Los permisos se asignan por proyecto y entorno, con roles predefinidos y la posibilidad de crear los tuyos. Un reparto que funciona bien en equipos pequeños es este.

Fíjate en que las identidades de máquina solo leen. Un pipeline no tiene por qué poder modificar un secreto, y limitarlo evita que un fallo en un script arrase la configuración de producción.

El registro de accesos

Cada consulta y cada cambio quedan anotados con usuario, momento y origen. Suena burocrático hasta el día que alguien pregunta si una clave filtrada se llegó a usar desde fuera, y tienes la respuesta en treinta segundos en lugar de en una semana de conjeturas.

También es lo que convierte la salida de una persona del equipo en un proceso ordenado: miras qué secretos tocó, rotas exactamente esos y revocas su cuenta, en lugar de cambiarlo todo por si acaso o —lo más habitual— no cambiar nada.

Versionado y vuelta atrás

Cada secreto guarda su historial de valores. Si alguien actualiza una cadena de conexión y la aplicación deja de arrancar, se recupera el valor anterior desde la interfaz sin buscar en el chat quién tenía la versión buena.

Un aviso útil sobre la rotación: cambiar el valor en Infisical Docker Compose no reinicia tus aplicaciones. Las que ya están corriendo siguen con el valor antiguo en memoria hasta que las reinicies, así que planifica el orden —primero acepta la credencial nueva en el servicio destino, luego rota, luego reinicia— si no quieres un corte.

Copias de seguridad de Infisical Docker Compose

En Infisical Docker Compose, respaldar la base de datos no basta: sin la clave de cifrado, ese volcado no vale absolutamente nada. Son dos piezas y hay que guardarlas por separado.

docker compose exec -T db pg_dump -U infisical infisical \
  | gzip > infisical-$(date +%F).sql.gz

Automatiza ese volcado con Duplicati y cifrado, y guarda la clave en un lugar completamente distinto: un gestor de contraseñas personal, un sobre en una caja fuerte, lo que sea, pero no en el mismo servidor. Para afinar el motor de base de datos aplica lo visto en PostgreSQL con Docker Compose.

Problemas frecuentes con Infisical Docker Compose

El primero es el fallo irreversible de Infisical Docker Compose y conviene repetirlo: cambiar la clave de cifrado en un despliegue con datos deja todos los secretos ilegibles. No es un fallo que se arregle reiniciando.

Conclusión sobre Infisical Docker Compose

Si trabajas solo y con dos proyectos, Infisical Docker Compose es exagerado y un fichero cifrado te resuelve la vida y esto es exagerado. El punto en que compensa llega cuando sois varios, hay entornos distintos y alguien tiene que poder desplegar sin conocer las credenciales de producción.

Empieza tu Infisical Docker Compose migrando un solo proyecto, con su entorno de desarrollo, y comprueba que la aplicación arranca leyendo los secretos desde ahí. Cuando ese circuito funcione, mover producción es trámite. Tienes la guía en la documentación de autoalojamiento, la lista completa de variables en su referencia de configuración, el código en GitHub, la herramienta de línea de comandos en su documentación, el proyecto en su web y más ideas en los tutoriales de Docker Compose.

Preguntas frecuentes sobre Infisical Docker Compose