Skip to main content
This guide walks you through storing secrets in Infisical and injecting them 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:

​
Step 1: Configure in Infisical

​
Create a project

In Infisical, a project holds all secrets for one application or service. To create a project:
1
Log in to Infisical.
2
Select Secrets Management > + Add New Project.
3
In the Project Name field, enter a name for the project (e.g., orders-service).
4
Select Create Project.
This opens your new project in the Development environment:
New project
Within a project, secrets are organized across environments. Every new project starts with three environments: Development, Staging, and Production.

​
Add your secrets

You have two options for adding secrets to your project:
To create a new secret from scratch:
1
Select + Add a New Secret.
2
In the Key and Value fields, enter a key-value pair. For example:
Key and Value fields
3
Select Create Secret.
4
Repeat these steps for each key-value pair you want to add.

​
Step 2: Choose a delivery method

Next, choose how Docker should receive your application secrets:
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.

​
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.

​
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.

​
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.

​
Update your Dockerfile

Add the Infisical CLI installation that matches your base image:
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:
Use the --command option when your application needs to run multiple shell commands in sequence:

​
Build and run your container

Build your image:
On the machine where Docker runs, authenticate the machine identity and start the container using the commands for your Infisical deployment:
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.

​
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:
Authenticate the machine identity in the same shell, then start the services using the commands for your Infisical deployment:
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:
Authenticate each identity before starting the services:

​
Next steps

Core Concepts

Understand how projects, environments, folders, and secrets fit together.

Secrets Delivery

Explore other ways to deliver secrets to applications and infrastructure.

Machine Identities

Configure workload authentication and access controls.

Infisical Run

Review all options for injecting secrets into an application process.