> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development

> This guide will help you set up and run the Infisical platform in local development.

## Fork and clone the repo

[Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the [repository](https://github.com/Infisical/infisical) to your own GitHub account and then [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) it to your local device.

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

```console theme={"dark"}
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](https://github.com/Infisical/infisical/blob/main/.env.dev.example). View all available [environment variables](https://infisical.com/docs/self-hosting/configuration/envars) 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

```bash theme={"dark"}
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](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:

```bash theme={"dark"}
# 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](https://github.com/mailhog/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.

| Variable            | Value                  |
| ------------------- | ---------------------- |
| `SMTP_HOST`         | `host.docker.internal` |
| `SMTP_PORT`         | `1025`                 |
| `SMTP_FROM_ADDRESS` | `dev@infisical.local`  |
| `SMTP_FROM_NAME`    | `Infisical Local`      |
| `SMTP_REQUIRE_TLS`  | `false`                |
| `SMTP_USERNAME`     | `you@example.com`      |
| `SMTP_PASSWORD`     | *(empty)*              |

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

#### Queue Management with BullBoard

The dev Docker Compose includes [BullBoard](https://github.com/felixmosh/bull-board), 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:

```bash theme={"dark"}
docker compose -f docker-compose.dev.yml --profile queue up
```

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

#### Shutdown local server

```bash theme={"dark"}
# 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](https://mintlify.com/) for our docs.

#### Install Mint CLI.

```bash theme={"dark"}
npm i -g mint
```

or

```bash theme={"dark"}
yarn global add mint
```

#### Running the docs

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

```bash theme={"dark"}
# From the root directory
cd docs; mint dev;
```