Inject secrets into a Docker application

Store secrets in Infisical and deliver them to a Dockerized application at runtime.

This guide walks you through injecting secrets from Infisical into a Dockerized application as environment variables. You can fetch secrets when the container starts or export them from the host when you run the container.

Visual learner? Watch an overview of managing secrets in Docker with Infisical.

Prerequisites

• An Infisical account on Infisical Cloud or a self-hosted instance
• A project with secrets configured
• Docker installed
• The Infisical CLI installed on the machine where you run Docker
• An application or container image to run

Setup

Choose how Docker should receive your application secrets:

Fetch at startup (Recommended)

This method installs the Infisical CLI in your image and uses it to start your application. The CLI fetches secrets when the container starts and injects them into the application process.

We strongly recommend this method, since it works for both local development and automated/production environments.

Step 1: Create a machine identity

Create a machine identity for your application:

1. In your project, select Project Settings > Access Control > Machine Identities.

2. Select Add Machine Identity, then select Create New.

3. Enter a name (e.g., orders-service-docker), select a role that can read secrets, and select Create.

Infisical creates the identity with Universal Auth enabled and opens its details page.

Step 2: Create a client secret

Create credentials that the application can exchange for a short-lived access token:

1. In the machine identity’s Authentication section, select Universal Auth.

2. Copy the Client ID and save it somewhere secure for the next step.

3. Select Create Client Secret, enter a description (e.g., docker-quickstart), and select Create.

4. Copy the Client Secret. You won’t be able to view it again.

Don’t add the Client ID, Client Secret, or an Infisical access token to your Dockerfile. Docker images may be shared or stored in a registry.

Machine identity access tokens are short-lived. Token expiration doesn’t affect an application after infisical run has fetched its secrets, but the container needs a valid token every time it starts.

In automated deployments, store the Client ID and Client Secret in your deployment platform’s secret store and run infisical login immediately before each docker run or docker compose up.

Step 3: Copy your project ID

In your project, select Project Settings, then select Copy Project ID. You’ll add this ID to your Dockerfile in the next step.

Step 4: Update your Dockerfile

Add the Infisical CLI installation that matches your base image:

Alpine

RUN apk add --no-cache bash wget \
    && wget -qO- 'https://artifacts-cli.infisical.com/setup.apk.sh' | sh \
    && apk add --no-cache infisical

Pin the Infisical CLI version in production images to keep builds reproducible.

Next, wrap your application’s start command with infisical run. Replace <project-id> with the project ID you copied earlier:

Node.js

CMD ["infisical", "run", "--projectId=<project-id>", "--env=dev", "--", "npm", "start"]

Run multiple startup commands

Use the --command option when your application needs to run multiple shell commands in sequence:

CMD ["infisical", "run", "--projectId=<project-id>", "--env=dev", "--command", "npm run migrate && npm start"]

Step 5: Build and run your container

Build your image:

docker build -t orders-service .

On the machine where Docker runs, authenticate the machine identity and start the container using the commands for your Infisical deployment:

Infisical Cloud US

export INFISICAL_TOKEN=$(infisical login \
  --method=universal-auth \
  --client-id=<client-id> \
  --client-secret=<client-secret> \
  --plain \
  --silent)

docker run --rm --env INFISICAL_TOKEN orders-service

If your self-hosted Infisical instance is running locally on the Docker host, don’t set INFISICAL_DOMAIN to a localhost URL, since this will point to the container itself.

Instead, set it to a host.docker.internal URL, which points to the container’s host domain.

Replace <client-id> and <client-secret> with the machine identity credentials you created earlier. The access token is passed to the container at runtime and isn’t stored in the image.

Your application can now read secrets as environment variables when the container starts.

Docker Run (Interactive)

Alternatively, you can run the Infisical CLI on the host and pass exported secrets to an existing image through Docker’s --env-file option. This method doesn’t require you to install the CLI in the image.

This method requires a Bash-compatible shell because it uses process substitution.

Step 1: Authenticate with the CLI

Authenticate with Infisical by running infisical login:

infisical login

This prompts you to select your hosting option, then opens your browser to complete the login.

Step 2: Connect your project

In your application’s directory, link it to the project you created by running infisical init:

infisical init

Follow the prompts to select your organization and project.

Step 3: Run your container

Export the secrets from the Development environment and pass them to your container:

docker run --rm \
  --env-file <(infisical export --env=dev --format=dotenv) \
  orders-service

Replace orders-service with the image you want to run. Infisical serves the exported secrets through a temporary file descriptor rather than writing a .env file to disk.

Docker’s --env-file option doesn’t support multiline secret values. Use the startup method if your application requires multiline secrets.

Your container can now read the exported secrets as environment variables.

Docker Run (CI/CD)

In CI/CD and other automated environments, use a machine identity to authenticate the Infisical CLI on the host. The CLI exports your application secrets and passes them to an existing image through Docker’s --env-file option.

This method requires a Bash-compatible shell because it uses process substitution.

Step 1: Configure machine identity access

Create a machine identity with permission to read the required secrets, configure it with Universal Auth, and copy its Client ID and Client Secret. Then copy the Project ID from Project Settings.

Store these values in your automation platform’s secret store rather than in source control.

Step 2: Authenticate with the CLI

Exchange the machine identity credentials for a short-lived access token using the commands for your Infisical deployment:

Infisical Cloud US

export INFISICAL_TOKEN=$(infisical login \
  --method=universal-auth \
  --client-id=<client-id> \
  --client-secret=<client-secret> \
  --plain \
  --silent)

Step 3: Run your container

Identify the project explicitly when exporting secrets, then pass them to the container:

docker run --rm \
  --env-file <(infisical export --projectId=<project-id> --env=dev --format=dotenv) \
  orders-service

Replace <project-id> with your project ID and orders-service with the image you want to run.

Docker’s --env-file option doesn’t support multiline secret values. Use the startup method if your application requires multiline secrets.

Your automation can now authenticate without a user session and inject secrets into the container.

Use with Docker Compose

If you fetch secrets at startup, you can use Docker Compose to build and run one or more configured service images.

Configure each image to start through infisical run, then configure your Compose file for your Infisical deployment:

Infisical Cloud US

services:
  orders-service:
    build: .
    environment:
      INFISICAL_TOKEN: ${INFISICAL_TOKEN}

Authenticate the machine identity in the same shell, then start the services using the commands for your Infisical deployment:

Infisical Cloud US

export INFISICAL_TOKEN=$(infisical login \
  --method=universal-auth \
  --client-id=<client-id> \
  --client-secret=<client-secret> \
  --plain \
  --silent)

docker compose up --build

If your self-hosted Infisical instance is running locally on the Docker host, don’t set INFISICAL_DOMAIN to a localhost URL, since this will point to the container itself.

Instead, set it to a host.docker.internal URL, which points to the container’s host domain.

Use different permissions for each service

If multiple services need different access permissions, create a machine identity for each permission set and pass each access token through a separate variable.

Map each service to the access token for its machine identity:

Infisical Cloud US

services:
  web:
    build: ./web
    environment:
      INFISICAL_TOKEN: ${INFISICAL_TOKEN_WEB}

  api:
    build: ./api
    environment:
      INFISICAL_TOKEN: ${INFISICAL_TOKEN_API}

Authenticate each identity before starting the services:

Infisical Cloud US

export INFISICAL_TOKEN_WEB=$(infisical login \
  --method=universal-auth \
  --client-id=<web-client-id> \
  --client-secret=<web-client-secret> \
  --plain \
  --silent)

export INFISICAL_TOKEN_API=$(infisical login \
  --method=universal-auth \
  --client-id=<api-client-id> \
  --client-secret=<api-client-secret> \
  --plain \
  --silent)

docker compose up --build