habsi/authentik
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

website/docs: Clarify frontend development. Document local overrides. (#13586)

Browse Source 
* website/docs: Clarify setup flow. Document local overrides.

* Update website/docs/developer-docs/setup/frontend-dev-environment.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/frontend-dev-environment.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/frontend-dev-environment.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/frontend-dev-environment.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/frontend-dev-environment.md

Co-authored-by: Dominic R <dominic@sdko.org>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/frontend-dev-environment.md

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/full-dev-environment.mdx

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/install-config/install/docker-compose.mdx

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/frontend-dev-environment.md

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

* Update website/docs/developer-docs/setup/full-dev-environment.mdx

Signed-off-by: Teffen Ellis <592134+GirlBossRush@users.noreply.github.com>

* Update authentik/lib/default.yml

Signed-off-by: Teffen Ellis <592134+GirlBossRush@users.noreply.github.com>

* fix linting to please the ci check

---------

Signed-off-by: Teffen Ellis <592134+GirlBossRush@users.noreply.github.com>
Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>
Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
Co-authored-by: Dominic R <dominic@sdko.org>
Co-authored-by: Marcelo Elizeche Landó <marcelo@goauthentik.io>
This commit is contained in:
Teffen Ellis
2025-03-27 17:49:16 +01:00
committed by GitHub
parent d72def0368
commit 8c7d4d2f5e
6 changed files with 166 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
authentik/lib/default.yml
View File

@ -1,5 +1,20 @@
# update website/docs/install-config/configuration/configuration.mdx
# This is the default configuration file
# authentik configuration
#
# https://docs.goauthentik.io/docs/install-config/configuration/
#
# To override the settings in this file, run the following command from the repository root:
#
# ```shell
# make gen-dev-config
# ```
#
# You may edit the generated file to override the configuration below.
#
# When making modifying the default configuration file,
# ensure that the corresponding documentation is updated to match.
#
# @see {@link ../../website/docs/install-config/configuration/configuration.mdx Configuration documentation} for more information.
postgresql:
host: localhost
name: authentik

116
scripts/generate_config.py
View File

@ -5,45 +5,85 @@ from yaml import safe_dump
from authentik.lib.generators import generate_id
with open("local.env.yml", "w", encoding="utf-8") as _config:
safe_dump(
{
"debug": True,
"log_level": "debug",
"secret_key": generate_id(),
"postgresql": {
"user": "postgres",
},
"outposts": {
"container_image_base": "ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s",
"disable_embedded_outpost": False,
},
"blueprints_dir": "./blueprints",
"cert_discovery_dir": "./certs",
"events": {
"processors": {
"geoip": "tests/GeoLite2-City-Test.mmdb",
"asn": "tests/GeoLite2-ASN-Test.mmdb",
}
},
"storage": {
"media": {
"backend": "file",
"s3": {
"endpoint": "http://localhost:8020",
"access_key": "accessKey1",
"secret_key": "secretKey1",
"bucket_name": "authentik-media",
"custom_domain": "localhost:8020/authentik-media",
"secure_urls": False,
},
def generate_local_config():
"""Generate a local development configuration"""
# TODO: This should be generated and validated against a schema, such as Pydantic.
return {
"debug": True,
"log_level": "debug",
"secret_key": generate_id(),
"postgresql": {
"user": "postgres",
},
"outposts": {
"container_image_base": "ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s",
"disable_embedded_outpost": False,
},
"blueprints_dir": "./blueprints",
"cert_discovery_dir": "./certs",
"events": {
"processors": {
"geoip": "tests/GeoLite2-City-Test.mmdb",
"asn": "tests/GeoLite2-ASN-Test.mmdb",
}
},
"storage": {
"media": {
"backend": "file",
"s3": {
"endpoint": "http://localhost:8020",
"access_key": "accessKey1",
"secret_key": "secretKey1",
"bucket_name": "authentik-media",
"custom_domain": "localhost:8020/authentik-media",
"secure_urls": False,
},
},
"tenants": {
"enabled": False,
"api_key": generate_id(),
},
},
_config,
default_flow_style=False,
"tenants": {
"enabled": False,
"api_key": generate_id(),
},
}
if __name__ == "__main__":
config_file_name = "local.env.yml"
with open(config_file_name, "w", encoding="utf-8") as _config:
_config.write(
"""
# Local authentik configuration overrides
#
# https://docs.goauthentik.io/docs/install-config/configuration/
#
# To regenerate this file, run the following command from the repository root:
#
# ```shell
# make gen-dev-config
# ```
"""
)
safe_dump(
generate_local_config(),
_config,
default_flow_style=False,
)
print(
f"""
---
Generated configuration file: {config_file_name}
For more information on how to use this configuration, see:
https://docs.goauthentik.io/docs/install-config/configuration/
---
"""
)

65
website/docs/developer-docs/setup/frontend-dev-environment.md
View File

@ -1,51 +1,82 @@
---
title: Frontend-only development environment
title: Frontend development environment
sidebar_label: Frontend development
tags:
- development
- contributor
- frontend
- docker
---
If you want to only make changes on the UI, you don't need a backend running from source. You can user the docker-compose install with a few customizations.
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 (any recent version should work; we use 22.x to build)
- Make (again, any recent version should work)
- Docker and Docker Compose
- [Node.js](https://nodejs.org/en) (22 or later)
- [Docker](https://www.docker.com/) (Latest Community Edition or Docker Desktop)
- [Docker Compose](https://docs.docker.com/compose/) (Compose v2)
- [Make](https://www.gnu.org/software/make/) (3 or later)
:::info
Depending on platform, some native dependencies might be required. On macOS, run `brew install node@22`, and for Docker `brew install --cask docker`
:::
### Instructions
1. Clone the git repo from https://github.com/goauthentik/authentik.
2. In the cloned repository, follow the docker-compose installation instructions [here](../../install-config/install/docker-compose).
3. Add the following entry to your `.env` file:
1. Clone the Git repo to your development machine and navigate to the authentik directory.
```shell
git clone https://github.com/goauthentik/authentik
cd authentik
```
:::info Beta images
By default, authentik will use the latest stable Docker images.
You can opt into using beta images during development by creating a `.env` file in the root of the repository with the following variables:
```shell
AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-next
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-next
AUTHENTIK_LOG_LEVEL=debug
```
This will cause authentik to use the beta images.
:::
4. Add this volume mapping to your compose file.
2. From the cloned repository, follow the Docker Compose [installation instructions](../../install-config/install/docker-compose).
```yaml
3. Create a Docker Compose override to mount the local configuration file (`local.env.yml`) and ESBuild's output directory (`web`).
```yaml title="docker-compose.override.yml"
services:
# [...]
server:
# [...]
volumes:
- ./web:/web
- ./local.env.yml:/local.env.yml
```
This makes the local web files and the config file available to the authentik server.
By creating this file in the root of the repository, 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.
5. Run `docker compose up -d` to apply those changes to your containers.
6. `cd web`
7. Run `npm i` and then `npm run watch` to start the build process.
4. From the cloned repository root, install the front-end dependencies using NPM.
```shell
cd web
npm ci
```
5. From the cloned repository root, run the front-end build script.
```shell
make web-watch
```
6. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose.
```shell
docker compose up
```
You can now access authentik on http://localhost:9000 (or https://localhost:9443).

22
website/docs/developer-docs/setup/full-dev-environment.mdx
View File

@ -1,5 +1,12 @@
---
title: Full development environment
sidebar_label: Full development
tags:
- development
- contributor
- backend
- frontend
- docker
---
import Tabs from "@theme/Tabs";
@ -8,13 +15,14 @@ import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
## Requirements
- [Python](https://www.python.org/) 3.12
- [uv](https://docs.astral.sh/uv/getting-started/installation/), which is used to manage dependencies
- [Go](https://go.dev/) 1.23 or newer
- [Node.js](https://nodejs.org/en) 22 or newer
- [PostgreSQL](https://www.postgresql.org/) 16 or newer
- [Redis](https://redis.io/) (any recent version will do)
- [Docker](https://www.docker.com/) (Community Edition will do)
- [Python](https://www.python.org/) (3.12 or later)
- [uv](https://docs.astral.sh/uv/getting-started/installation/), (Latest stable release)
- [Go](https://go.dev/) (1.23 or later)
- [Node.js](https://nodejs.org/en) (22 or later)
- [PostgreSQL](https://www.postgresql.org/) (16 or later)
- [Redis](https://redis.io/) (7 or later)
- [Docker](https://www.docker.com/) (Latest Community Edition or Docker Desktop)
- [Docker Compose](https://docs.docker.com/compose/) (Compose v2)
## Services Setup

8
website/docs/developer-docs/setup/website-dev-environment.md
View File

@ -1,5 +1,11 @@
---
title: Website development environment
title: Docs development environment
sidebar_label: Docs development
tags:
- development
- contributor
- docs
- docusaurus
---
If you want to only make changes to the website, you only need node.

2
website/docs/install-config/install/docker-compose.mdx
View File

@ -8,7 +8,7 @@ This installation method is for test setups and small-scale production setups.
- A host with at least 2 CPU cores and 2 GB of RAM
- Docker
- Docker Compose (Compose v2 is recommended, see [here](https://docs.docker.com/compose/migrate/) for instructions on how to upgrade)
- Docker Compose (Compose v2, see [instructions for upgrade](https://docs.docker.com/compose/migrate/))
## Video