Local development

Fork and clone the repo

Fork the repository to your own GitHub account and then clone it to your local device.

Once, you've done that, create a new branch:

git checkout -b MY_BRANCH_NAME

Set up environment variables

Start by creating a .env file at the root of the Infisical directory then copy the contents of the file linked here. View all available environment variables and guidance for each.

Starting Infisical for development

We use Docker to spin up all required services for Infisical in local development. If you are unfamiliar with Docker, don’t worry, all you have to do is install Docker for your machine and run the command below to start up the development server.

Start local server

docker compose -f docker-compose.dev.yml up --build --force-recreate

Access local server

Once all the services have spun up, browse to http://localhost:8080.

If the backend image fails to build

The backend dev image is built on top of a prebuilt toolchain image (SoftHSM2, Oracle Instant Client, and two OpenSSL builds) that we publish to GHCR, so you don't have to spend ~15 minutes compiling it. The build pulls ghcr.io/infisical/backend-fips-toolchain:main by default.

If that pull fails (GHCR outage, no network, or you're working on the toolchain itself), build it locally once and point the backend build at it:

# Build the toolchain from source. Takes ~15 minutes.
docker build -f backend/Dockerfile.fips-toolchain -t fips-toolchain:local backend

# Point the backend build at your local copy by adding this to your .env
echo 'TOOLCHAIN_IMAGE=fips-toolchain:local' >> .env

Then start the stack as usual. Putting it in .env matters: the start command above uses --build, so a one-off TOOLCHAIN_IMAGE=... docker compose build would be ignored on the next up --build and you'd be back to a failing GHCR pull.

You only have to redo the first step if backend/Dockerfile.fips-toolchain changes. If you already have a working backend image and don't pass --build, a GHCR outage won't affect you at all.

Local SMTP with Mailhog

The dev Docker Compose includes Mailhog, a local SMTP server that captures all outgoing emails. This is useful for testing email-based flows like user invitations, password resets, and other notifications without sending real emails.

The .env.dev.example file already includes the SMTP variables pre-configured for Mailhog — no extra setup is needed.

To view captured emails, open the Mailhog web UI at http://localhost:8025.

Queue Management with BullBoard

The dev Docker Compose includes BullBoard, a web UI for monitoring and managing BullMQ job queues. This is useful for debugging async job processing, viewing queue status, and inspecting failed jobs during development.

To start BullBoard, use the queue profile:

docker compose -f docker-compose.dev.yml --profile queue up

Once running, access the BullBoard UI at http://localhost:3008 to view and manage queues in real-time.

Shutdown local server

# To stop environment use Control+C (on Mac) CTRL+C (on Win) or
docker compose -f docker-compose.dev.yml down

Starting Infisical docs locally

We use Mintlify for our docs.

Install Mint CLI.

npm i -g mint

or

yarn global add mint

Running the docs

Go to docs directory and run mint dev. This will start up the docs on localhost:3000

# From the root directory
cd docs; mint dev;