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
GitHub
parent
8d3275817b
commit
6f3d6efa22
3
Makefile
3
Makefile
|
|
@ -103,6 +103,9 @@ run:
|
|||
## Web
|
||||
#########################
|
||||
|
||||
web-build: web-install
|
||||
cd web && npm run build
|
||||
|
||||
web: web-lint-fix web-lint web-extract
|
||||
|
||||
web-install:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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)
|
||||
- Documentation should use American english
|
||||
|
|
|
|||
|
|
@ -2,21 +2,21 @@
|
|||
title: Full development environment
|
||||
---
|
||||
|
||||
## Backend
|
||||
|
||||
To create a local development setup for authentik, you need the following:
|
||||
|
||||
### Requirements
|
||||
## Requirements
|
||||
|
||||
- Python 3.10
|
||||
- poetry, which is used to manage dependencies, and can be installed with `pip install poetry`
|
||||
- Go 1.18
|
||||
- PostgreSQL (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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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`.
|
||||
|
||||
```
|
||||
cd web/
|
||||
npm i
|
||||
npm run build
|
||||
```
|
||||
Alternatively, if you want to live-edit the UI, you can run `make web-watch` instead.
|
||||
This will immediately update the UI with any changes you make so you can see the results in real time without needing to rebuild.
|
||||
|
||||
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`.
|
||||
|
|
|
|||
Reference in a new issue