trustchain-oc1-orchestral
/
authentik
Archived
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

webiste/docs: Improve clarity of dev environment setup doc (#3045) 

* Improve clarity of dev environment setup doc

* Requested changes and further small improvements

* I actually read the makefile this time

* Add makefile entry for building ui

* Comments

* Add documentation setup

* Move documentation setup

* Formatting
This commit is contained in:
Keval Kapdee 2022-06-05 22:26:08 +01:00 committed by GitHub
parent 8d3275817b
commit 6f3d6efa22
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 36 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Makefile
View File

@ -103,6 +103,9 @@ run:
## Web ## Web
######################### #########################
web-build: web-install
cd web && npm run build
web: web-lint-fix web-lint web-extract web: web-lint-fix web-lint web-extract
web-install: web-install:

18
website/developer-docs/docs/writing-documentation.md
View File

@ -5,7 +5,23 @@ title: Writing documentation
Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. Here are a few guidelines to ensure Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. Here are a few guidelines to ensure
the documentation is easy to read and uses similar phrasing. the documentation is easy to read and uses similar phrasing.
# General guidelines ## Setup
Requirements:
- Node 16 (or greater)
The documentation site is situated in the `/website` folder of the authentik GitHub repository.
The site is built using npm, below are some useful make commands:
- Install: `make website-install` (Needed for any of the other tasks)
- Formatting: `make website-lint-fix` or `make website` (Run this before committing)
- Live editing: `make website-watch` (For real time viewing of changes)
Be sure to run the formatter before committing changes.
## General guidelines
- authentik should always be stylized as `authentik` (with a lower-case a and ending with a k) - authentik should always be stylized as `authentik` (with a lower-case a and ending with a k)
- Documentation should use American english - Documentation should use American english

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

@ -2,21 +2,21 @@
title: Full development environment title: Full development environment
--- ---
## Backend ## Requirements
To create a local development setup for authentik, you need the following:
### Requirements
- Python 3.10 - Python 3.10
- poetry, which is used to manage dependencies, and can be installed with `pip install poetry` - poetry, which is used to manage dependencies, and can be installed with `pip install poetry`
- Go 1.18 - Go 1.18
- PostgreSQL (any recent version will do) - PostgreSQL (any recent version will do)
- Redis (any recent version will do) - Redis (any recent version will do)
- Node 16 (or later)
For PostgreSQL and Redis, you can use the docker-compose file in `scripts/`. You can also use a native install, if you prefer. ## Services Setup
### Setup For PostgreSQL and Redis, you can use the docker-compose file in `scripts/`.
You can also use a native install, if you prefer.
## Backend Setup
```shell ```shell
poetry shell # Creates a python virtualenv, and activates it in a new shell poetry shell # Creates a python virtualenv, and activates it in a new shell
@ -36,8 +36,6 @@ secret_key: "A long key you can generate with `pwgen 40 1` for example"
To apply database migrations, run `make migrate`. This is needed after the initial setup, and whenever you fetch new source from upstream. To apply database migrations, run `make migrate`. This is needed after the initial setup, and whenever you fetch new source from upstream.
Afterwards, you can start authentik by running `make run`. authentik is now accessible under `localhost:9000`.
Generally speaking, authentik is a Django application, ran by gunicorn, proxied by a Go application. The Go application serves static files. 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. 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.
@ -46,18 +44,17 @@ Before committing code, run `make lint` to ensure your code is formatted well. T
Run `make gen` to generate an updated OpenAPI document for any changes you made. Run `make gen` to generate an updated OpenAPI document for any changes you made.
## Frontend ## Frontend Setup
By default, no compiled bundle of the frontend is included. To build the UI, you need Node 14 or newer. By default, no compiled bundle of the frontend is included so this step is required even if you're not developing for the UI.
To build the UI, run these commands: To build the UI once, run `web-build`.
``` Alternatively, if you want to live-edit the UI, you can run `make web-watch` instead.
cd web/ This will immediately update the UI with any changes you make so you can see the results in real time without needing to rebuild.
npm i
npm run build
```
If you want to make changes to the UI, run `npm run watch` instead. To format the frontend code, run `make web`.
To ensure the code is formatted well, run `npx eslint . --fix` and `npm run lit-analyse`. ## Running
Now that the backend and frontend have been setup and built, you can start authentik by running `make run`. authentik should now be accessible at `http://localhost:9000`.