From 84de15568a7d27167beb2beef80135cd0ae2e976 Mon Sep 17 00:00:00 2001 From: Ken Sternberg <133134217+kensternberg-authentik@users.noreply.github.com> Date: Fri, 10 Jan 2025 12:53:05 -0800 Subject: [PATCH] website: revise full development environment instructions (#12638) * website: revise full development environment instructions Updates the full development environment instructions to make it clear you *will* need both Docker and Golangci-Lint installed. Adds the `poetry-plugin-shell` requirement, now that Poetry requires it. Updates the per-platform development environment requirements to have a Linux-specific section, and update the MacOS section to include poetry-plugin-shell and golangci-lint Moves the instructions on what to do before committing to the bottom of the document; its location was confusing and didn't clarify what steps were to be taken in what order. Includes the instruction that, for a first-time run, you must run `make migrate` and `make gen` or the TS-API won't be built, and in turn the WebUI build would otherwise fail. We still need instructions for Windows. * Prettier had opinions. * Format error: "macOS," not "MacOS" * Fixed some typos and cleaned up some prompts. * Fixed 'under windows' -> 'on Windows' --- .../setup/full-dev-environment.md | 105 ++++++++++++++---- 1 file changed, 84 insertions(+), 21 deletions(-) diff --git a/website/docs/developer-docs/setup/full-dev-environment.md b/website/docs/developer-docs/setup/full-dev-environment.md index bd1801751407..d14050a7ea59 100644 --- a/website/docs/developer-docs/setup/full-dev-environment.md +++ b/website/docs/developer-docs/setup/full-dev-environment.md @@ -2,14 +2,20 @@ title: Full development environment --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; + ## Requirements -- Python 3.12 -- Poetry, which is used to manage dependencies -- Go 1.23 or newer -- Node.js 21 or newer -- PostgreSQL 14 or newer -- Redis (any recent version will do) +- [Python](https://www.python.org/) 3.12 +- [Poetry](https://python-poetry.org/), which is used to manage dependencies + - Poetry 2.0 or higher also requires the [poetry-plugin-shell](https://github.com/python-poetry/poetry-plugin-shell) extension. +- [Go](https://go.dev/) 1.23 or newer +- [Node.js](https://nodejs.org/en) 21 or newer +- [PostgreSQL](https://www.postgresql.org/) 14 or newer +- [Redis](https://redis.io/) (any recent version will do) +- [Docker](https://www.docker.com/) (Community Edition will do) ## Services Setup @@ -23,53 +29,100 @@ If you use locally installed databases, the PostgreSQL credentials given to auth ## Backend Setup :::info -Depending on your platform, some native dependencies might be required. On macOS, run `brew install libxmlsec1 libpq krb5`, and for the CLI tools `brew install postgresql redis node@20`. +Depending on your platform, some native dependencies might be required. + + { +const ua = window.navigator.userAgent.toLowerCase(); +return ["linux", "windows", "mac"].find((p) => ua.includes(p)) || "mac"; +})() : "mac" } + +values={[ +{label: "macOS", value: "mac"}, +{label: "Linux", value: "linux"}, +{label: "Windows", value: "windows"}, +]}> + + + To install the native dependencies on macOS, run: + + ```sh + $ pip install poetry poetry-plugin-shell + $ brew install libxmlsec1 libpq krb5 # Required development libraries, + $ brew install postgresql redis node@22 golangci-lint # Required CLI tools + ``` + + + + + To install native dependencies on Debian or Ubuntu, run: + +```sh +$ pip install poetry poetry-plugin-shell +$ sudo apt-get install libgss-dev krb5-config libkrb5-dev postgresql-server-dev-all +$ sudo apt-get install postresql redis +``` + +Adjust your needs as required for other distributions such as Red Hat, SUSE, or Arch. + +Install golangci-lint locally [from the site +instructions](https://golangci-lint.run/welcome/install/#other-ci). + + + +[We request community input on running the full dev environment on Windows] + + + ::: 1. Create an isolated Python environment. To create the environment and install dependencies, run the following commands in the same directory as your local authentik git repository: ```shell -poetry shell # Creates a python virtualenv, and activates it in a new shell -make install # Installs all required dependencies for Python and Javascript, including development dependencies +poetry shell # Creates a python virtualenv, and activates it in a new shell +make install # Installs all required dependencies for Python and Javascript, including development dependencies ``` 2. Configure authentik to use the local databases using a local config file. To generate this file, run the following command in the same directory as your local authentik git repository: ```shell -make gen-dev-config # Generates a local config file +make gen-dev-config # Generates a local config file ``` Generally speaking, authentik is a Django application, ran by gunicorn, proxied by a Go application. The Go application serves static files. Most functions and classes have type-hints and docstrings, so it is recommended to install a Python Type-checking Extension in your IDE to navigate around the code. -Before committing code, run the following commands in the same directory as your local authentik git repository: - -```shell -make lint # Ensures your code is well-formatted -make gen # Generates an updated OpenAPI Docs for any changes you make -``` - ## Frontend Setup By default, no compiled bundle of the frontend is included so this step is required even if you're not developing for the UI. +The UI requires the authentik API files for Typescript be built and installed: + +``` +$ make migrate # On a fresh install, ensures the API schema file is available +$ make gen # Generates the API based on the schema file +``` + +If you make changes to the authentik API, you must re-run `make gen` so that the corresponding +changes are made to the API library that is used by the UI. + To build the UI once, run the following command in the same directory as your local authentik git repository: ```shell -make web-build # Builds the UI once +make web-build # Builds the UI once ``` If you want to live-edit the UI, you can run the following command in the same directory as your local authentik git repository instead, which will immediately update the UI with any changes you make so you can see the results in real time without needing to rebuild: ```shell -make web-watch # Updates the UI with any changes you make +make web-watch # Updates the UI with any changes you make ``` To format the frontend code, run the following command in the same directory as your authentik git repository: ```shell -make web # Formats the frontend code +make web # Formats the frontend code ``` ## Running authentik @@ -77,7 +130,7 @@ make web # Formats the frontend code Now that the backend and frontend have been setup and built, you can start authentik by running the following command in the same directory as your local authentik git repository: ```shell -ak server # Starts authentik server +ak server # Starts authentik server ``` And now, authentik should now be accessible at `http://localhost:9000`. @@ -87,3 +140,13 @@ To define a password for the default admin (called **akadmin**), you can manuall 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. ::: + +## Submitting Pull Requests + +Before submitting a pull request, run the following commands in the same directory as your local authentik git repository: + +```shell +make lint # Ensures your code is well-formatted +make gen # Generates an updated OpenAPI Docs for any changes you make +make web # Formats the front-end code +```