Step-by-step self-hosting of Infisical on a VPS with HTTPS, Nginx, machine identities, systemd, Docker, build-time…
Complete Docker guides with optimization techniques, deployment strategies, and automation prompts to streamline your containerization workflow.
No spam. Unsubscribe anytime.
Self-hosting Infisical gives any application a central, provider-neutral place to store secrets, separate development, staging, and production values, and issue separate identities to developers and servers, all without tying your setup to Vercel, a single cloud provider, or a stack-specific SDK. This guide covers the complete implementation: standing up Infisical on a dedicated VPS behind HTTPS, structuring projects and environments, creating machine identities for staging and production, and injecting secrets into systemd services and Docker containers. Everything here works for any application that reads configuration from environment variables, and I'll use my own Next.js and Payload CMS stack as the running example throughout.
In the previous article, I covered why .env files stop being a sufficient secrets-management system once an application picks up multiple developers, deployment environments, servers, and external services. This one covers what replaces them. I wanted something that felt close to managing environment variables in Vercel, without being tied to Vercel, and that would work across local development, staging, production, Docker containers, background workers, and plain VPS deployments regardless of framework. Infisical is what I landed on, and this guide walks through the full setup.
.env filesThe end result looks like this regardless of what you're running:
Developer laptop
└── Infisical CLI
└── development secrets
Staging VPS
└── staging machine identity
└── staging secrets
Production VPS
└── production machine identity
└── production secrets
Infisical VPS
├── Infisical
├── PostgreSQL
├── Redis
└── HTTPS reverse proxy
Your application keeps reading ordinary environment variables through whatever mechanism your language or framework already uses, process.env in Node.js being the obvious one. Infisical controls where those values are stored, who may retrieve them, and which environment each application receives. The application code itself doesn't need to know Infisical exists.
This guide assumes Ubuntu or Debian on the servers, Docker and Docker Compose on the Infisical VPS, a domain such as secrets.example.com, separate staging and production servers, and a small team or small-scale production deployment. The application examples use Next.js with Payload CMS and pnpm, since that's the stack I run most often, but nothing about Infisical itself is specific to that combination. Swap in a Django app, a Go service, a Rails app, or anything else that reads configuration from the environment, and the Infisical side of this guide stays the same.
Infisical's official Docker Compose template runs the application, PostgreSQL, and Redis on a single Docker host. Infisical documents this deployment model as suitable for development, testing, proofs of concept, and smaller deployments that don't require high availability, with a documented minimum of two CPU cores, 4 GB RAM, and 20 GB disk for the complete stack, and higher resources recommended beyond that.
For this guide, I'd use at least:
4 vCPU
8 GB RAM
50 GB SSD
A smaller server works fine for testing, but a secrets manager is infrastructure that every one of your applications may depend on during startup, so I'd rather give it comfortable headroom from the start. For a larger organization or a high-availability requirement, run Infisical against external PostgreSQL and Redis services or a more resilient orchestration setup.
The Infisical server should sit separately from your application servers, regardless of what those application servers run.
Internet
│
▼
secrets.example.com
│
▼
Nginx with TLS
│
▼
Infisical container
├── PostgreSQL container
└── Redis container
Application servers connect to the Infisical API over HTTPS:
Production VPS
│
├── Client ID
├── Client Secret
│
▼
Infisical Universal Auth
│
▼
Short-lived access token
│
▼
Production secrets
│
▼
Application process
The application server never stores the database password, application secret, storage credentials, SMTP password, and every external API key in a local .env.production file. It stores one restricted bootstrap credential that lets it request the correct secrets from Infisical, and that's true whether the process at the bottom of that chain is Next.js, Payload, or something else entirely.
Start by creating a dedicated installation directory:
sudo mkdir -p /opt/infisical
sudo chown "$USER":"$USER" /opt/infisical
cd /opt/infisical
Verify that Docker and Docker Compose are installed:
docker --version
docker compose version
Download the official Docker Compose template and example configuration:
curl -fsSL \
-o docker-compose.prod.yml \
https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml
curl -fsSL \
-o .env \
https://raw.githubusercontent.com/Infisical/infisical/main/.env.example
Protect the configuration file:
chmod 600 .env
The downloaded .env contains example credentials that must not be used in production. Infisical explicitly marks the example encryption and authentication values as unsafe for production use.
The current official Compose template contains:
image: infisical/infisical:latest
It also includes a comment telling operators to pin the image to a specific tag. Open the file:
nano docker-compose.prod.yml
Change:
image: infisical/infisical:latest
To a specific version that you've reviewed:
image: infisical/infisical:<PINNED_VERSION>
A floating latest tag has no place in infrastructure that stores the credentials for every other application you run. The same principle applies to PostgreSQL and Redis: pin versions, test upgrades in a non-production environment, back up the database, and upgrade deliberately.
The official template publishes the backend directly on port 80:
ports:
- 80:8080
I prefer to expose Infisical only through the reverse proxy. Change the backend port mapping to:
services:
backend:
ports:
- "127.0.0.1:8080:8080"
The service is now reachable from the VPS itself at http://127.0.0.1:8080 and stays off the public network interface. Nginx will terminate TLS and forward requests to this local port.
Infisical requires an encryption key and an authentication secret. Generate the encryption key:
openssl rand -hex 16
Generate the authentication secret:
openssl rand -base64 32
Generate a PostgreSQL password using hexadecimal characters so it can safely appear inside a connection URI:
openssl rand -hex 24
Infisical currently documents ENCRYPTION_KEY as a random 16-byte hexadecimal string and AUTH_SECRET as a random 32-byte Base64 string. Open the configuration:
nano /opt/infisical/.env
Replace the sample values with your generated values:
# File: /opt/infisical/.env
ENCRYPTION_KEY=<GENERATED_HEX_ENCRYPTION_KEY>
AUTH_SECRET=<GENERATED_BASE64_AUTH_SECRET>
POSTGRES_USER=infisical
POSTGRES_PASSWORD=<GENERATED_POSTGRES_PASSWORD>
POSTGRES_DB=infisical
DB_CONNECTION_URI=postgresql://infisical:<GENERATED_POSTGRES_PASSWORD>@db:5432/infisical
REDIS_URL=redis://redis:6379
SITE_URL=https://secrets.example.com
TELEMETRY_ENABLED=false
Leave the rest of the optional integration settings empty unless you need them. The platform requires an absolute SITE_URL, including the protocol. PostgreSQL is the persistent data layer here, and Redis handles caching and background work.
Check the permissions again:
chmod 600 /opt/infisical/.env
Start the stack:
cd /opt/infisical
docker compose \
-f docker-compose.prod.yml \
up -d
Check the containers:
docker compose \
-f docker-compose.prod.yml \
ps
Inspect the logs if a container isn't healthy:
docker compose \
-f docker-compose.prod.yml \
logs --tail=100
Test the local API:
curl -fsS http://127.0.0.1:8080/api/status
You should get a successful response from the Infisical backend.
Install Nginx and Certbot:
sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx
Create the Nginx virtual host:
sudo nano /etc/nginx/sites-available/secrets.example.com
Add:
# File: /etc/nginx/sites-available/secrets.example.com
server {
listen 80;
listen [::]:80;
server_name secrets.example.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 300;
proxy_send_timeout 300;
}
}
Enable the site:
sudo ln -s \
/etc/nginx/sites-available/secrets.example.com \
/etc/nginx/sites-enabled/secrets.example.com
Test the configuration and reload Nginx:
sudo nginx -t
sudo systemctl reload nginx
Make sure the DNS record points to the Infisical VPS:
secrets.example.com A <INFISICAL_VPS_IP>
Then request the certificate:
sudo certbot \
--nginx \
-d secrets.example.com
Verify the result:
curl -fsS https://secrets.example.com/api/status
Running the public Infisical interface over plain HTTP isn't an option here. Infisical uses secure cookies for authenticated sessions, and its own documentation recommends SSL for self-hosted deployments.
Open https://secrets.example.com and create your account as soon as the installation becomes reachable. In the Docker Compose installation flow, the first registered user becomes the instance administrator, so this step needs to happen before the instance is shared or widely exposed. For a stricter initial setup, temporarily restrict port 443 to your IP address while creating the first account.
After creating the administrator, configure SMTP for password resets and invitations, invite the developers who need access, enable multi-factor authentication, review whether public sign-up should stay available, and confirm that only the reverse proxy can reach the backend port.
Infisical uses email for invitations, password resets, and notifications. Add the SMTP configuration to /opt/infisical/.env:
# File: /opt/infisical/.env
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=<SMTP_USERNAME>
SMTP_PASSWORD=<SMTP_PASSWORD>
SMTP_FROM_ADDRESS=secrets@example.com
SMTP_FROM_NAME=Infisical
Restart the backend:
cd /opt/infisical
docker compose \
-f docker-compose.prod.yml \
restart backend
Test the password-reset flow before relying on the instance for production infrastructure.
In Infisical, create a Secrets Management project:
Project name: My Application
Configure three environments:
Development dev
Staging staging
Production prod
Infisical projects organize secrets into environments, folders, and individual values, and the same key can exist in each environment with a different value. Using a Next.js and Payload stack as an example:
| Key | Development | Staging | Production |
|---|---|---|---|
DATABASE_URL | Local database | Staging database | Production database |
PAYLOAD_SECRET | Development value | Staging value | Production value |
S3_BUCKET | Development bucket | Staging bucket | Production bucket |
BREVO_API_KEY | Test or development key | Staging key | Production key |
Keep the key names consistent across environments regardless of what framework is consuming them. A starting set for a Payload application might look like:
# File: Infisical → My Application → dev/staging/prod
NODE_ENV=production
APP_ENV=
SERVER_URL=
DATABASE_URL=
DATABASE_URL_UNPOOLED=
PAYLOAD_SECRET=
S3_ENDPOINT=
S3_REGION=
S3_BUCKET=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
REDIS_URL=
SMTP_HOST=
SMTP_PORT=
SMTP_USERNAME=
SMTP_PASSWORD=
BREVO_API_KEY=
CRON_SECRET=
PREVIEW_SECRET=
A different stack would list different keys, but the structure, one project, three environments, consistent naming, stays the same. You can import an existing .env file through the Infisical interface, but review every value first and make sure it lands in the correct environment.
.env.example in GitInfisical becomes the source of truth for the actual secret values, but the repository should still document which variables the application expects. Create:
# File: .env.example
NODE_ENV=
APP_ENV=
SERVER_URL=
DATABASE_URL=
DATABASE_URL_UNPOOLED=
PAYLOAD_SECRET=
S3_ENDPOINT=
S3_REGION=
S3_BUCKET=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
REDIS_URL=
SMTP_HOST=
SMTP_PORT=
SMTP_USERNAME=
SMTP_PASSWORD=
BREVO_API_KEY=
CRON_SECRET=
PREVIEW_SECRET=
This documents the configuration contract without containing credentials, and it's worth keeping around no matter which application reads it.
On macOS:
brew install infisical/get-cli/infisical
On Debian or Ubuntu:
curl -1sLf \
"https://artifacts-cli.infisical.com/setup.deb.sh" \
| sudo -E bash
sudo apt-get update
sudo apt-get install -y infisical
Infisical also distributes the CLI through NPM:
npm install -g @infisical/cli
For a production server, pin the CLI version instead of silently installing an arbitrary future release. Infisical explicitly recommends version pinning for production environments.
Navigate to the application directory, whatever it contains:
cd /path/to/my-application
Log in:
infisical login
The current CLI can interactively select a self-hosted instance, or you can define your domain explicitly:
export INFISICAL_DOMAIN="https://secrets.example.com"
Initialize the project:
infisical init
Select the Infisical project when prompted. This creates .infisical.json. Update it to include the self-hosted domain and default environment:
{
"workspaceId": "<INFISICAL_PROJECT_ID>",
"defaultEnvironment": "dev",
"domain": "https://secrets.example.com"
}
Infisical's project configuration file stores the project reference, default environment, and optional self-hosted domain. The documentation notes that this file is usually committed to the repository, so review the configured domain carefully before committing it. The file itself never contains the secret values.
Your application code doesn't need to import an Infisical SDK. For a Next.js and Payload project, Payload keeps reading its configuration from process.env exactly as before:
// File: src/payload.config.ts
import { buildConfig } from 'payload'
import { postgresAdapter } from '@payloadcms/db-postgres'
export default buildConfig({
secret: process.env.PAYLOAD_SECRET ?? '',
serverURL: process.env.SERVER_URL,
db: postgresAdapter({
pool: {
connectionString: process.env.DATABASE_URL,
},
}),
})
Payload officially supports reading environment variables directly from process.env inside its configuration, and the same is true for essentially any framework that reads configuration from the process environment. Start the application through Infisical:
infisical run --env=dev -- pnpm dev
Infisical retrieves the development values and injects them into the pnpm dev process. Swap pnpm dev for whatever your stack uses to start locally, python manage.py runserver, go run ., rails server, and the pattern holds. You can add a convenience script:
{
"scripts": {
"dev": "next dev",
"dev:secrets": "infisical run --env=dev -- pnpm dev",
"build": "next build",
"start": "next start"
}
}
Run:
pnpm dev:secrets
Verify that a value exists without printing the value itself:
infisical run --env=dev -- \
node -e "console.log('DATABASE_URL available:', Boolean(process.env.DATABASE_URL))"
Expected output:
DATABASE_URL available: true
Runtime injection through infisical run covers most frameworks completely, but a few tools also embed configuration into a build artifact rather than reading it purely at runtime. Next.js is the clearest example, so it's worth walking through even in an otherwise stack-agnostic setup.
Server-side values like these should never be prefixed with NEXT_PUBLIC_:
DATABASE_URL
PAYLOAD_SECRET
S3_SECRET_ACCESS_KEY
SMTP_PASSWORD
BREVO_API_KEY
A value prefixed with NEXT_PUBLIC_ is meant for browser access:
NEXT_PUBLIC_SITE_URL
NEXT_PUBLIC_ANALYTICS_ID
NEXT_PUBLIC_MAPBOX_TOKEN
Next.js replaces NEXT_PUBLIC_ references during next build, embedding the values directly into the browser bundle, where they stay fixed after the build completes. If your framework has an equivalent build-time embedding step, check its documentation for the same distinction before wiring up Infisical, since the fix is always the same: run the build itself through infisical run so the values are present at build time, not just at process startup. Never solve a missing browser variable by marking a secret public.
Developers should log in as themselves. Servers, regardless of what they run, shouldn't use a developer account. For production, create a machine identity:
Organization Settings
→ Access Control
→ Identities
→ Create identity
Name it clearly:
my-application-production
Configure Universal Auth, which gives the machine identity a Client ID and Client Secret. The server exchanges these for a short-lived access token. Next, add the identity to the project:
Project Settings
→ Access Control
→ Machine Identities
→ Add identity
Grant it read-only access to:
Project: My Application
Environment: Production
Path: /
The production identity should never read development, staging, or unrelated client projects. Create a separate identity for staging:
my-application-staging
Give it access only to the staging environment. The identities stay separate because their permission sets are different, and that separation matters regardless of what's actually running on either server.
The production server still needs an initial credential that lets it authenticate to Infisical. Create a dedicated application user if one doesn't already exist:
sudo adduser --system \
--group \
--home /srv/my-application \
my-application
Create the configuration directory:
sudo install \
-d \
-m 750 \
-o root \
-g my-application \
/etc/my-application
Create the bootstrap file:
sudo nano /etc/my-application/infisical.env
Add:
# File: /etc/my-application/infisical.env
INFISICAL_DOMAIN=https://secrets.example.com
INFISICAL_PROJECT_ID=<PROJECT_ID>
INFISICAL_ENV=prod
INFISICAL_CLIENT_ID=<PRODUCTION_CLIENT_ID>
INFISICAL_CLIENT_SECRET=<PRODUCTION_CLIENT_SECRET>
INFISICAL_DISABLE_UPDATE_CHECK=true
Protect it:
sudo chown root:my-application \
/etc/my-application/infisical.env
sudo chmod 640 \
/etc/my-application/infisical.env
This file is the remaining secret-zero credential. It's still sensitive, but it's far narrower than a complete production .env file: it can be revoked independently, and its permissions can be limited to one project and one environment, no matter what application ends up consuming the secrets it unlocks.
Create:
sudo nano /usr/local/bin/my-application-infisical
Add:
#!/usr/bin/env bash
# File: /usr/local/bin/my-application-infisical
set -euo pipefail
set -a
source /etc/my-application/infisical.env
set +a
export PATH="/usr/local/bin:/usr/bin:/bin"
export INFISICAL_TOKEN="$(
infisical login \
--method=universal-auth \
--client-id="$INFISICAL_CLIENT_ID" \
--client-secret="$INFISICAL_CLIENT_SECRET" \
--silent \
--plain
)"
exec infisical run \
--projectId="$INFISICAL_PROJECT_ID" \
--env="$INFISICAL_ENV" \
--path="/" \
-- "$@"
Make it executable:
sudo chmod 750 \
/usr/local/bin/my-application-infisical
sudo chown root:my-application \
/usr/local/bin/my-application-infisical
The wrapper does two things: it exchanges the Universal Auth credentials for a short-lived access token, then starts whatever command you hand it with the correct secrets injected. Infisical's CLI requires --projectId when authenticating through a machine identity, and it selects the environment and path through --env and --path. Because the wrapper just wraps a command, it works identically whether that command is pnpm start, gunicorn, or a compiled Go binary.
Test it:
sudo -u my-application \
/usr/local/bin/my-application-infisical \
node -e "console.log(Boolean(process.env.PAYLOAD_SECRET))"
Expected output:
true
Some frameworks, Next.js and Payload among them, need environment variables present while evaluating configuration during the build or a migration step, not just at process startup. Run the build through the wrapper:
cd /srv/my-application/current
sudo -u my-application \
/usr/local/bin/my-application-infisical \
pnpm build
Run Payload migrations through the same wrapper:
cd /srv/my-application/current
sudo -u my-application \
/usr/local/bin/my-application-infisical \
pnpm payload migrate
The migration now receives the production database connection from Infisical rather than from a local file. Run migrations before restarting the production application, and confirm a recent database backup exists first.
Create the service:
sudo nano /etc/systemd/system/my-application.service
Add:
# File: /etc/systemd/system/my-application.service
[Unit]
Description=My application
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=my-application
Group=my-application
WorkingDirectory=/srv/my-application/current
ExecStart=/usr/local/bin/my-application-infisical pnpm start
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production
Environment=PATH=/usr/local/bin:/usr/bin:/bin
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
Swap pnpm start in ExecStart for whatever command actually starts your application. Reload systemd, then enable and start it:
sudo systemctl daemon-reload
sudo systemctl enable --now my-application
Check the status and follow the logs:
sudo systemctl status my-application
sudo journalctl -u my-application -f
The startup flow is now the same regardless of stack: systemd calls the execution wrapper, which logs in through Universal Auth, gets a short-lived access token, runs infisical run, and finally starts your application.
Suppose you replace BREVO_API_KEY. Update the value in the production environment inside Infisical. The currently running process will still have the old value in memory, since environment variables don't update inside an already running process. Restart the service:
sudo systemctl restart my-application
Infisical supports a --watch option that restarts a command automatically when secrets change, but its documentation recommends that feature for development rather than production. I prefer explicit production restarts tied to a reviewed configuration change, and that preference holds regardless of what's running behind the wrapper.
For a Docker deployment, install the Infisical CLI inside the application image. For an Alpine-based image:
# File: Dockerfile
RUN apk add --no-cache bash curl
RUN curl -1sLf \
"https://artifacts-cli.infisical.com/setup.apk.sh" \
| sh
RUN apk add --no-cache infisical
Create an entrypoint:
# File: docker/infisical-entrypoint.sh
#!/usr/bin/env bash
set -euo pipefail
export INFISICAL_TOKEN="$(
infisical login \
--method=universal-auth \
--client-id="$INFISICAL_CLIENT_ID" \
--client-secret="$INFISICAL_CLIENT_SECRET" \
--silent \
--plain
)"
exec infisical run \
--projectId="$INFISICAL_PROJECT_ID" \
--env="$INFISICAL_ENV" \
--path="${INFISICAL_PATH:-/}" \
-- "$@"
Copy it into the image:
# File: Dockerfile
COPY docker/infisical-entrypoint.sh \
/usr/local/bin/infisical-entrypoint
RUN chmod +x \
/usr/local/bin/infisical-entrypoint
ENTRYPOINT ["/usr/local/bin/infisical-entrypoint"]
CMD ["pnpm", "start"]
The application image still starts its normal command; the entrypoint adds the authentication and secret-injection step in front of it. Infisical's Docker integration follows this same general pattern for any base image: install the CLI in the container and use infisical run as the wrapper around whatever the container was already going to run.
Store the bootstrap credentials on the host:
sudo mkdir -p /etc/my-application
sudo nano \
/etc/my-application/infisical.env
Add:
# File: /etc/my-application/infisical.env
INFISICAL_DOMAIN=https://secrets.example.com
INFISICAL_PROJECT_ID=<PROJECT_ID>
INFISICAL_ENV=prod
INFISICAL_CLIENT_ID=<CLIENT_ID>
INFISICAL_CLIENT_SECRET=<CLIENT_SECRET>
Protect the file:
sudo chmod 600 \
/etc/my-application/infisical.env
The Compose service can use it:
# File: docker-compose.production.yml
services:
app:
image: my-application:<VERSION>
restart: unless-stopped
env_file:
- /etc/my-application/infisical.env
environment:
NODE_ENV: production
INFISICAL_DISABLE_UPDATE_CHECK: "true"
ports:
- "127.0.0.1:3000:3000"
Start it:
docker compose \
-f docker-compose.production.yml \
up -d
Check the logs:
docker compose \
-f docker-compose.production.yml \
logs --tail=100 app
The container receives only the bootstrap configuration through the host file, and the actual application secrets get retrieved when the container starts. A user with unrestricted access to the Docker daemon effectively has root-level control over every container and its configuration, so access to Docker itself needs to stay restricted regardless of which secrets manager sits behind it.
Runtime injection doesn't automatically cover build-time variables. This matters most for anything like Next.js's NEXT_PUBLIC_* values, which get embedded during the build step rather than read at container startup.
When building the image, provide the Infisical access token as a BuildKit secret rather than a normal Docker build argument. Authenticate on the build machine:
export INFISICAL_DOMAIN="https://secrets.example.com"
export INFISICAL_TOKEN="$(
infisical login \
--method=universal-auth \
--client-id="$INFISICAL_CLIENT_ID" \
--client-secret="$INFISICAL_CLIENT_SECRET" \
--silent \
--plain
)"
Build:
DOCKER_BUILDKIT=1 docker build \
--secret id=infisical_token,env=INFISICAL_TOKEN \
--build-arg INFISICAL_PROJECT_ID="$INFISICAL_PROJECT_ID" \
--build-arg INFISICAL_ENV="$INFISICAL_ENV" \
--build-arg INFISICAL_DOMAIN="$INFISICAL_DOMAIN" \
-t my-application:<VERSION> \
.
In the builder stage:
# File: Dockerfile
ARG INFISICAL_PROJECT_ID
ARG INFISICAL_ENV
ARG INFISICAL_DOMAIN
RUN --mount=type=secret,id=infisical_token,required=true \
export INFISICAL_TOKEN="$(cat /run/secrets/infisical_token)" && \
export INFISICAL_DOMAIN="$INFISICAL_DOMAIN" && \
infisical run \
--projectId="$INFISICAL_PROJECT_ID" \
--env="$INFISICAL_ENV" \
--path="/" \
-- pnpm build
The access token gets mounted only for that build instruction instead of landing in a normal image layer or build argument. Keep in mind that any value your framework deliberately marks as public, like NEXT_PUBLIC_* in Next.js, is meant to end up in the browser bundle. BuildKit protects the Infisical token here, not values you've already decided should be public.
For a single application process, storing secrets at the project root is usually enough:
/
As the architecture grows, folders can separate access:
/
├── app
├── workers
├── migrations
└── automation
The web process might receive /app, a background worker /workers, and a migration job /migrations, regardless of what language each of those components is written in. Infisical supports injecting secrets from one or several paths:
infisical run \
--path="/app" \
--path="/shared" \
-- pnpm start
Don't build out a complicated folder hierarchy before you actually have different permission requirements. Folders earn their place once genuinely separate workloads need different subsets of secrets.
To rotate the production Client Secret, generate a new Client Secret for the existing machine identity, add it to /etc/my-application/infisical.env, restart the application, confirm it starts correctly, and revoke the old Client Secret. The new process authenticates with the new bootstrap credential immediately. None of this requires rotating the database password, storage key, or any other application secret just because the machine identity credential changed, which is one of the main benefits of separating application secrets from machine authentication in the first place.
The PostgreSQL database contains the persistent Infisical data. Create a dump:
cd /opt/infisical
docker compose \
-f docker-compose.prod.yml \
exec -T db \
pg_dump \
-U infisical \
infisical \
| gzip \
> "infisical-$(date +%F-%H%M%S).sql.gz"
The official Docker Compose guide identifies the PostgreSQL volume as the critical persistent store and provides pg_dump as the backup mechanism, but the database alone isn't the complete recovery plan. Your deployment also depends on /opt/infisical/.env, which contains ENCRYPTION_KEY, AUTH_SECRET, POSTGRES_PASSWORD, and SITE_URL. Because ENCRYPTION_KEY is required for Infisical's own encryption and decryption operations, a working recovery plan needs both the database backup and the original platform encryption key together.
Back up the following through an encrypted backup system: the PostgreSQL dump, /opt/infisical/.env, docker-compose.prod.yml, the Nginx configuration, TLS and DNS recovery information, and the pinned Infisical version. Keep the only copy off the Infisical VPS itself, and actually test restoring it. An untested backup is a guess, not a recovery plan.
Without --watch, infisical run retrieves secrets when the application starts and injects them into the new process. Once an application is running, its environment variables already sit in process memory, so a temporary Infisical outage won't stop that existing process. It can, however, block a new deployment, an application restart, a container replacement, a server reboot, a migration command, or a new worker from starting, no matter what that worker happens to run.
That's why the Infisical instance itself needs monitoring, database backups, resource headroom, controlled upgrades, a documented restore process, and a stable domain with a valid TLS certificate. A secrets manager removes configuration sprawl, and it also becomes part of your deployment control plane, so it deserves the same operational care as anything else on that critical path.
Set the self-hosted domain:
export INFISICAL_DOMAIN="https://secrets.example.com"
Or add it to .infisical.json:
{
"domain": "https://secrets.example.com"
}
401 or 403Check whether the Client ID is correct, whether the Client Secret is current, whether the identity was actually added to the project, and whether it has access to the selected environment and folder path. Authentication and project access are separate steps, so a machine identity can authenticate successfully and still lack access to a project.
Check INFISICAL_PROJECT_ID, INFISICAL_ENV, INFISICAL_DOMAIN, INFISICAL_PATH, the production machine identity's permissions, and outbound HTTPS connectivity from the server. The staging identity shouldn't be assumed to have production access just because it exists in the same project.
Restart the process:
sudo systemctl restart my-application
Or recreate the container:
docker compose \
-f docker-compose.production.yml \
up -d \
--force-recreate
Environment variables don't mutate inside an already running process, in Node.js or anywhere else.
NEXT_PUBLIC_* is still oldRebuild the application. Next.js freezes NEXT_PUBLIC_ values during next build, so restarting the existing build artifact won't pick up a new value; the build has to run again.
Confirm the restored deployment uses the original ENCRYPTION_KEY. A database dump without the matching encryption configuration is an incomplete recovery package.
Check:
curl -fsS http://127.0.0.1:8080/api/status
curl -fsS https://secrets.example.com/api/status
sudo nginx -t
sudo journalctl -u nginx --tail=100
Also confirm that SITE_URL=https://secrets.example.com matches the actual public URL.
.env filesBefore this setup, a developer laptop held .env.local, the staging VPS held .env.staging, the production VPS held .env.production, and the CI runner held its own copy of the production values, all independently. After this setup, Infisical holds development, staging, and production centrally, developers authenticate with a personal login, and the staging and production servers authenticate through their own machine identities.
The application code stays just as simple as it was before:
process.env.DATABASE_URL
process.env.PAYLOAD_SECRET
process.env.S3_SECRET_ACCESS_KEY
What changed is entirely operational: one source of truth, consistent key names, explicit environment separation, separate human and machine access, revocable server credentials, a documented startup workflow, and a repeatable recovery model, none of which depends on which framework or language sits on top of it.
Does Infisical only work with Node.js applications?
No. Infisical's CLI wraps any command through infisical run -- <command>, so it works the same way for a Python, Go, Ruby, or PHP process as it does for Next.js or Payload. The examples here use Node.js because that's the stack I run, but the pattern generalizes directly.
Do I need separate Infisical projects for separate applications? Usually yes, one project per application keeps environments and access boundaries clean, especially when different applications belong to different clients. A small internal toolset with shared ownership can sometimes live in one project with folders separating the pieces, but that's a judgment call based on who needs access to what.
What's the actual difference between Infisical and a tool like Vault? Infisical focuses on a simpler, Vercel-like mental model of projects, environments, and secrets, with a CLI and dashboard that get you running quickly. HashiCorp Vault and OpenBao add dynamic credentials, PKI, and more advanced policy engines, at the cost of more operational complexity. Most small-to-mid-size teams get everything they need from Infisical without touching Vault's extra surface area.
Can I run Infisical without Docker? The official deployment path is Docker Compose, which is also the path documented and supported by Infisical itself. Running it another way is possible in principle but puts you outside the tested deployment model, so I'd stick with Docker Compose unless you have a specific reason not to.
What happens to my running application if the Infisical server goes down? Nothing, as long as the application is already running, since its environment variables live in process memory once the process has started. An Infisical outage blocks new deployments, restarts, and container replacements until the instance comes back, which is exactly why it needs its own monitoring and backup plan.
Self-hosting Infisical doesn't remove environment variables from the picture. It gives them a proper management and delivery system that works the same way no matter what's consuming them. Developers authenticate as people, application servers authenticate as machine identities, staging and production receive separate values, and the application itself keeps reading standard environment variables without getting tightly coupled to a vendor-specific SDK.
The critical implementation decisions carry across any stack: run Infisical on dedicated infrastructure, put it behind HTTPS, pin the deployed versions, keep the backend port private, separate development, staging, and production, use Universal Auth for VPS workloads, store only restricted bootstrap credentials locally, restart production explicitly after secret changes, handle build-time values where your framework requires it, and back up both PostgreSQL and the Infisical encryption configuration together.
The result is a provider-neutral secrets workflow that works across local development, systemd, Docker, and whatever application framework you're actually running, Next.js and Payload CMS included.
For the broader reasoning behind this setup, read How to Manage Environment Variables and Secrets Across Environments. For the complete application deployment layer, read Self-Host Next.js and Payload on VPS: Complete Guide.
Let me know in the comments if you have questions, and subscribe for more practical development guides.
Thanks, Matija