authentik/website/docs/developer-docs/setup/frontend-dev-environment.md

title, sidebar_label, tags

title	sidebar_label	tags
Frontend development environment	Frontend development	development contributor frontend docker

If you're focusing solely on frontend development, you can create a minimal development environment using Docker and Node.js. This setup allows you to make and preview changes to the frontend in real-time, without needing to interact with the backend.

Prerequisites

• Node.js (24 or later)
• Docker (Latest Community Edition or Docker Desktop)
• Docker Compose (Compose v2)
• Make (3 or later)

Instructions

1. Clone the Git repo to your development machine and navigate to the authentik directory.

   git clone https://github.com/goauthentik/authentik
   cd authentik
   

2. Run the following to create a .env file in the lifecycle/container directory of the repository to configure the Docker Compose environment.

   echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> ./lifecycle/container/.env
   echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> ./lifecycle/container/.env
   echo "AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server" >> ./lifecycle/container/.env
   echo "AUTHENTIK_TAG=gh-next" >> ./lifecycle/container/.env
   echo "AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-next" >> ./lifecycle/container/.env
   echo "AUTHENTIK_LOG_LEVEL=debug" >> ./lifecycle/container/.env
   echo 'GIT_BUILD_HASH="dev"' >> ./lifecycle/container/.env
   

3. Create a Docker Compose override file (compose.override.yml) in the root of the repository. This will override the volume configurations for the local configuration file (local.env.yml) and mount the directory for the frontend code (web) into the docker containers. Docker will automatically mount the web files generated by the build process. The local.env.yml mount is optional, but allows you to override the default configuration.

   services:
       server:
           volumes:
               - ./web:/web
               - ./local.env.yml:/local.env.yml
   

4. From the repository root, run the frontend build script. This will install the npm packages needed to run the frontend project and start the project in watch mode.

   make node-install
   make web-watch
   

5. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose.

   docker compose -f lifecycle/container/compose.yml up -d
   

You can now access authentik on http://localhost:9000 (or https://localhost:9443).