Skip to main content

Full development environment

Prerequisites​

Before you begin, ensure you have the following tools installed. You can run the provided script below in Installing platform-specific dependencies to install these required tools.

  • Python (3.14)
  • uv (Latest stable release)
  • Rust (We provide a rust-toolchain.toml file for the correct version, and we use the nightly toolchain to run formatting with rustfmt.)
  • Go (1.26 or later)
  • Node.js (24 or later), installed with nvm
  • pnpm (12.4 or later), the package manager used across every JavaScript workspace in the repository
  • PostgreSQL (16 or later)
  • Docker (Latest Community Edition or Docker Desktop)
  • Docker Compose (Compose v2)
  • Make (3 or later)
  • CMake (Latest stable release)

Understanding the architecture​

authentik is primarily a Django application running under gunicorn, proxied by a Go application that serves static files. Most functions and classes have type hints and docstrings. For better code navigation, we recommend installing a Python type-checking extension in your IDE.

1. Prepare your local working repository​

Verify that you have a local working repository of authentik and that it is initialized and up-to-date with the authentik repository.

Unless otherwise specified, all commands described below should be run from the project root of your local authentik repository.

2. Set up required services​

authentik depends on several external services:

The easiest way to set up these services is using the provided Docker Compose configuration:

docker compose -f scripts/compose.yml up -d

3. Installing platform-specific dependencies​

Install the required native dependencies on macOS using Homebrew. You can edit the following command if you already have some of these and want to skip installing them again, or run brew install --dry-run to preview the changes:

brew install \
libxmlsec1 \
libpq \
pkg-config \
uv \
postgresql \
golangci-lint \
krb5 \
cmake
warning

aws-lc-rs currently has an issue building its FIPS module with GCC >= 14. If you encounter this issue, you have two options:

  • Use an older version of GCC.
  • Install Clang and export AWS_LC_FIPS_SYS_CC=clang.

Installing Node.js and pnpm​

Install Node.js with nvm, one of the version managers recommended on the Node.js download page. It keeps the toolchain scoped to your shell rather than installed system-wide, so switching versions between projects doesn't require reinstalling:

nvm install 24
nvm use 24

Then install pnpm by following the pnpm installation guide. Any recent pnpm works: on each run it automatically switches to the version pinned in package.json.

info

nvm runs on macOS and Linux; on Windows, use nvm-windows, a separate project with its own command set.

4. Set up the backend​

info

All make commands must be executed from the root directory of your local authentik Git repository.

Install dependencies​

Install all required JavaScript and Python dependencies and create an isolated Python environment:

make install
Package install scripts are disabled by default

In this repository, pnpm is configured to not run a dependency's preinstall/install/postinstall lifecycle scripts unless that package is explicitly allow-listed. This neutralizes a dominant supply-chain attack pattern at the cost of skipping a few legitimate native-binary unpacks.

Each workspace keeps its allow-list in its own pnpm-workspace.yaml: onlyBuiltDependencies lists the packages whose scripts may run, and allowBuilds records an explicit true/false for each one so pnpm doesn't prompt for approval at install time.

If a build fails because a package needs its install script (commonly esbuild, chromedriver, tree-sitter, or tree-sitter-json), add it to both lists in the relevant pnpm-workspace.yaml, then rebuild just that package:

pnpm rebuild esbuild

Allow-listing a package grants it arbitrary code execution during install, so treat any addition as a change that needs review.

Generate development configuration​

Create a local configuration file that uses the local databases for development:

make gen-dev-config

Initialize the database​

Run all migrations with the following command:

make migrate
info

If you ever want to start over, use make dev-reset, which drops and restores the authentik PostgreSQL database to the state it was in after you ran make migrate.

5. Running authentik​

Now that the backend has been set up and built, you can start authentik. Run the following command from the root of your installation directory:

make run
info

The very first time authentik runs, it might need some time to clear the initial task queue. Adjust AUTHENTIK_WORKER__THREADS as required.

Hot-reloading​

When AUTHENTIK_DEBUG is set to true (the default for the development environment), the authentik server automatically reloads whenever changes are made to the code.

Install watchexec, and run:

make run-watch

6. Build the frontend​

Even if you're not planning to develop the UI, you need to build the frontend because no compiled bundle is included by default. Run the following command to build the authentik UI:

make web-build

For real-time feedback you can view the UI as you make changes. Run this command and then in your browser go to http://localhost:9000/.

make web-watch

7. Initial setup​

After the frontend build completes, set a password for the default admin user (akadmin):

  1. Navigate to http://localhost:9000 in your browser.
  2. Follow the prompts to set up your admin account.

From now on, you can access authentik at http://localhost:9000 using the credentials you defined in Step 2.

Troubleshooting​

Recovery key​

If you can no longer log in or the authentication flow repeats (perhaps due to an incorrectly configured stage or a failed flow import), you can create a recovery key by running this command in your terminal:

uv run ak create_recovery_key 10 akadmin

Copy the generated recovery key and paste it into the URL, after the domain. For example:

http://localhost:9000/recovery/use-token/ChFk2nJKJKJKY9OdIc8yv6RCgpGYp5rdndBhR6qHoHoJoWDdlvLuvU/

info

The recovery token is valid for a short time, but anyone can use it to log in as the admin user. Using the recovery token will also disable custom CSS in case you've accidentally locked yourself out of the admin interface with a broken theme.

End-to-end (E2E) setup​

authentik ships two end-to-end test suites:

  • The Django/Selenium suite under tests/e2e/ — driven by Django's test runner. It is exercised in CI by the test-e2e job in ci-main.yml.
  • The browser-side Playwright suite under web/test/browser/ — driven by web/playwright.config.js. It is exercised in CI by the e2e (playwright) job in ci-web.yml and runs against a live authentik server.

Django/Selenium suite​

Start the E2E test services with the following command:

docker compose -f tests/e2e/compose.yml up -d

You can then view the Selenium Chrome browser via http://localhost:7900/ using the password: secret.

Alternatively, you can connect directly via VNC on port 5900 using the password: secret.

info

When using Docker Desktop, host networking needs to be enabled via Docker Settings > Resources > Network > Enable host networking.

Playwright suite​

The Playwright suite assumes that:

  • An authentik stack is reachable at http://localhost:9000 (override with AK_TEST_RUNNER_PAGE_URL).
  • The akadmin user can log in as [email protected] with the password test-runner.

Both are satisfied by the development environment described above, as long as the bootstrap credentials match what the tests expect. Set them before authentik first starts — the bootstrap blueprint only applies them while akadmin still has no usable password:

export AUTHENTIK_BOOTSTRAP_EMAIL=[email protected]
export AUTHENTIK_BOOTSTRAP_PASSWORD=test-runner

make run

If your instance already has an akadmin password, either reset it to test-runner through the UI or point the suite at a different account via SessionFixture's defaults.

Install Playwright's browsers (one-time) and run the suite — these are the same scripts CI runs:

pnpm --dir web exec playwright install --with-deps chromium
pnpm --dir web run test:e2e

After a failing run, open the HTML report to inspect traces, screenshots, and (in CI) videos:

pnpm --dir web exec playwright show-report

In CI, the same artifacts are uploaded under the playwright-report and playwright-traces artifact names on the workflow run.

Contributing code​

Before submitting a pull request​

Ensure your code meets our quality standards by running:

  1. Code linting:

    make lint-fix
    make lint

  2. Generate updated API documentation:

    make gen

  3. Format frontend code:

    make web

  4. Run tests:

    make test

You can run all these checks at once with:

make all

Submit your changes​

After your code passes all checks, submit a pull request on GitHub. Be sure to:

  • Provide a clear description of your changes
  • Reference any related issues
  • Update any related documentation
  • Follow our code and documentation style guidelines
  • Include tests for your changes where appropriate

Thank you for contributing to authentik!