Skip to main content

Full development environment

Prerequisites​

Before you begin, ensure you have the following tools installed:

1. Setting 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/docker-compose.yml up -d

Option B: Using local installations​

Alternatively, you can install and run these services directly on your system.

info

If using locally installed databases, ensure the PostgreSQL credentials provided to authentik have CREATE DATABASE and DROP DATABASE permissions, because authentik creates temporary databases for testing.

2. Installing Platform-Specific Dependencies​

Install the required native dependencies on macOS using Homebrew:

brew install \
libxmlsec1 \
libpq \
krb5 \
pkg-config \
uv \
postgresql \
redis \
node@24 \
golangci-lint

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

Generate development configuration​

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

make gen-dev-config

Understanding the architecture​

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

4. Set up the frontend​

Even if you're not planning to develop the UI, you need to build the frontend as no compiled bundle is included by default.

Running database migrations​

First, apply all database migrations:

make migrate

Generating schema files​

Generate the required schema files and TypeScript client:

make gen
info

After making changes to the authentik API, you must re-run make gen to update the API library used by the UI.

Building the UI​

You have several options for building the UI:

One-time build​

make web-build

Live development mode​

For real-time feedback as you make changes:

make web-watch

Formatting frontend code​

After making changes:

make web

5. Running authentik​

Now that the backend and frontend have been set up and built, you can start authentik.

Start the server by running the following command in the same directory as your local authentik git repository:

make run-server   # Starts authentik server

Start the worker by running the following command in the same directory as your local authentik git repository:

make run-worker   # Starts authentik worker

Both processes need to run to get a fully functioning authentik development environment.

authentik will be accessible at http://localhost:9000.

Initial setup​

To set a password for the default admin user (akadmin):

  1. Navigate to http://localhost:9000/if/flow/initial-setup/ in your browser.
  2. Follow the setup wizard to create your admin account.
info

To define a password for the default admin (called akadmin), you can manually enter the /if/flow/initial-setup/ path in the browser address bar to launch the initial flow. Example: http://localhost:9000/if/flow/initial-setup/.

In case of issues in this process, feel free to use make dev-reset which drops and restores the authentik PostgreSQL instance to a "fresh install" state.

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. However, due to instabilities in the reloading process of the worker, that behavior is turned off for the worker. You can enable code reloading in the worker by manually running uv run ak worker --watch.

End-to-End (E2E) Setup​

To run E2E tests, navigate to the /tests/e2e directory in your local copy of the authentik git repo, and start the services by running docker compose 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.

note

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

6. Contributing code​

Before submitting a pull request​

Ensure your code meets our quality standards by running:

  1. Code linting:

    make lint

  2. Generate updated API documentation:

    make gen

  3. Format frontend code:

    make web

You can run all these checks at once with:

make lint gen web

Submitting your changes​

Once your code passes all checks, you can submit a pull request through GitHub. Be sure to:

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

Thank you for contributing to authentik!