website/docs/developer-docs/setup/full-dev-environment.mdx
import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs";
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.
rust-toolchain.toml file for the correct version, and we use the nightly toolchain to run formatting with rustfmt.)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.
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.
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
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 \
node@24 \
golangci-lint \
krb5
For Debian/Ubuntu-based distributions (you can edit the following command if you already have some of these and want to skip installing them again):
pip install uv
sudo apt-get install -y \
libgss-dev \
krb5-config \
libkrb5-dev \
postgresql-server-dev-all \
postgresql
For other distributions (Red Hat, SUSE, Arch), adjust the package names as needed.
Install golangci-lint by following the official installation instructions.
We're currently seeking community input on running the full development environment on Windows. If you have experience with this setup, please consider contributing to this documentation.
</TabItem> </Tabs>:::info
All make commands must be executed from the root directory of your local authentik Git repository.
:::
Install all required JavaScript and Python dependencies and create an isolated Python environment:
make install
Create a local configuration file that uses the local databases for development:
make gen-dev-config
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 after you ran after make migrate.
:::
Now that the backend has been set up and built, you can start authentik. In two different tabs in your terminal, run the following commands from the root of your installation directory:
make run-server
make run-worker
:::info
The very first time a worker runs, it might need some time to clear the initial task queue. Adjust AUTHENTIK_WORKER__THREADS as required.
:::
Both processes need to run to get a fully functioning authentik development environment.
To set a password for the default admin user (akadmin):
From now on, you can now access authentik at http://localhost:9000 using the credentials you defined in Step 2.
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
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.
If you can't login anymore 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/
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. :::
Ensure your code meets our quality standards by running:
Code linting:
make lint-fix
make lint
Generate updated API documentation:
make gen
Format frontend code:
make web
Run tests:
make test
You can run all these checks at once with:
make all
After your code passes all checks, submit a pull request on GitHub. Be sure to:
Thank you for contributing to authentik!