diff --git a/website/docs/developer-docs/setup/debug_vscode.png b/website/docs/developer-docs/setup/debug_vscode.png new file mode 100644 index 000000000000..4a461e7d8521 Binary files /dev/null and b/website/docs/developer-docs/setup/debug_vscode.png differ diff --git a/website/docs/developer-docs/setup/debugging.md b/website/docs/developer-docs/setup/debugging.md new file mode 100644 index 000000000000..eb5eeb4084a0 --- /dev/null +++ b/website/docs/developer-docs/setup/debugging.md @@ -0,0 +1,53 @@ +--- +title: Debugging authentik +--- + +This page describes how to debug different components of an authentik instance, running either in production or in a development setup. To learn more about the structure of authentik, refer to our [architecture documentation](../../core/architecture). + +## authentik Server & Worker (Python) + +The majority of the authentik codebase is in Python, running in Gunicorn for the server and Celery for the worker. These instructions show how this code can be debugged/inspected. The local debugging setup requires a setup as described in [Full development environment](./full-dev-environment.mdx) + +Note that authentik uses [debugpy](https://github.com/microsoft/debugpy), which relies on the "Debug Adapter Protocol" (DAP). These instructions demonstrate debugging using [Visual Studio Code](https://code.visualstudio.com/), however they should be adaptable to other editors that support DAP. + +To enable the debugging server, set the environment variable `AUTHENTIK_DEBUGGER` to `true`. This will launch the debugging server (by default on port _9901_). + +With this setup in place, you can set Breakpoints in VS Code. To connect to the debugging server, run the command `> Debug: Start Debugging" in VS Code. + +![](./debug_vscode.png) + +:::info +Note that due to the Python debugger for VS Code, when a Python file in authentik is saved and the Django process restarts, you must manually reconnect the Debug session. Automatic re-connection is not supported for the Python debugger (see [here](https://github.com/microsoft/vscode-python/issues/19998) and [here](https://github.com/microsoft/vscode-python/issues/1182)). +::: + +#### Debugging in containers + +When debugging an authentik instance running in containers, there are some additional steps that need to be taken in addition to the steps above. + +A local clone of the authentik repository is required to be able to set breakpoints in the code. The locally checked out repository must be on the same version/commit as the authentik version running in the containers. To checkout version 2024.12.3 for example, you can run `git checkout version/2024.12.3`. + +The debug port needs to be accessible on the local machine. By default, this is port 9901. Additionally, the container being debugged must be started as `root`, because additional dependencies need to be installed on startup. + +When running in Docker Compose, a file `docker-compose.override.yml` can be created next to the authentik docker-compose.yml file to expose the port, change the user, and enable debug mode. + +```yaml +services: + # Replace `server` with `worker` to debug the worker container. + server: + user: root + healthcheck: + disable: true + environment: + AUTHENTIK_DEBUGGER: "true" + AUTHENTIK_LOG_LEVEL: "debug" + ports: + - 9901:9901 +``` + +After re-creating the containers with `AUTHENTIK_DEBUGGER` set to `true` and the port mapped, the steps are identical to the steps above. + +If the authentik instance is running on a remote server, the `.vscode/launch.json` file needs to be adjusted to point to the IP of the remote server. Alternatively, it is also possible to forward the debug port via an SSH tunnel, using `-L 9901:127.0.0.1:9901`. + +## authentik Server / Outposts (Golang) + +Outposts, as well as some auxiliary code of the authentik server, are written in Go. These components can be debugged using standard Golang tooling, such as [Delve](https://github.com/go-delve/delve). diff --git a/website/docs/developer-docs/setup/full-dev-environment.md b/website/docs/developer-docs/setup/full-dev-environment.mdx similarity index 95% rename from website/docs/developer-docs/setup/full-dev-environment.md rename to website/docs/developer-docs/setup/full-dev-environment.mdx index d14050a7ea59..f18319b58a0c 100644 --- a/website/docs/developer-docs/setup/full-dev-environment.md +++ b/website/docs/developer-docs/setup/full-dev-environment.mdx @@ -2,9 +2,9 @@ title: Full development environment --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment"; ## Requirements @@ -70,7 +70,9 @@ instructions](https://golangci-lint.run/welcome/install/#other-ci). -[We request community input on running the full dev environment on Windows] + + [We request community input on running the full dev environment on Windows] + diff --git a/website/docs/install-config/configuration/configuration.mdx b/website/docs/install-config/configuration/configuration.mdx index 323867ea8dba..619fc4cbdc94 100644 --- a/website/docs/install-config/configuration/configuration.mdx +++ b/website/docs/install-config/configuration/configuration.mdx @@ -167,6 +167,7 @@ Additionally, you can set `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECK` to perform h - `AUTHENTIK_LISTEN__LDAPS`: Listening address:port (e.g. `0.0.0.0:6636`) for LDAPS (Applies to LDAP outpost) - `AUTHENTIK_LISTEN__METRICS`: Listening address:port (e.g. `0.0.0.0:9300`) for Prometheus metrics (Applies to All) - `AUTHENTIK_LISTEN__DEBUG`: Listening address:port (e.g. `0.0.0.0:9900`) for Go Debugging metrics (Applies to All) +- `AUTHENTIK_LISTEN__DEBUG_PY`: Listening address:port (e.g. `0.0.0.0:9901`) for Python debugging server (Applies to Server, see [Debugging](../../developer-docs/setup/debugging.md)) - `AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS`: List of comma-separated CIDRs that proxy headers should be accepted from (Applies to Server) Defaults to `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fe80::/10`, `::1/128`. diff --git a/website/sidebars.js b/website/sidebars.js index 91dad4cf7170..cfa3ad2ab633 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -607,11 +607,12 @@ export default { items: [ { type: "category", - label: "Setup", + label: "Development environment", items: [ "developer-docs/setup/full-dev-environment", "developer-docs/setup/frontend-dev-environment", "developer-docs/setup/website-dev-environment", + "developer-docs/setup/debugging", ], }, {