From 33e79036995a6e7f3dd178830c15d1489b06f993 Mon Sep 17 00:00:00 2001 From: Jens L Date: Mon, 31 Jul 2023 11:21:33 +0200 Subject: [PATCH] website/docs: add architecture and persistence (#6250) * website/docs: add architecture and persistence Signed-off-by: Jens Langhammer * Apply suggestions from code review Co-authored-by: Tana M Berry Signed-off-by: Jens L. * Apply suggestions from code review Co-authored-by: Tana M Berry Signed-off-by: Jens L. * add note about kubernetes Signed-off-by: Jens Langhammer * link to relevant parts Signed-off-by: Jens Langhammer --------- Signed-off-by: Jens Langhammer Signed-off-by: Jens L. Co-authored-by: Tana M Berry --- website/docs/core/architecture.md | 61 +++++++++++++++++++++ website/docs/installation/docker-compose.md | 32 +++-------- website/sidebars.js | 1 + 3 files changed, 69 insertions(+), 25 deletions(-) create mode 100644 website/docs/core/architecture.md diff --git a/website/docs/core/architecture.md b/website/docs/core/architecture.md new file mode 100644 index 000000000..a6059cc86 --- /dev/null +++ b/website/docs/core/architecture.md @@ -0,0 +1,61 @@ +--- +title: Architecture +--- + +authentik consists of a handful of components, most of which are required for a functioning setup. + +```mermaid +graph LR + user(User) --> ak_server(authentik Server) + ak_server --> ak_server_core(authentik Server Core) + ak_server --> ak_outpost(Embedded outpost) + ak_server_core --> db(PostgreSQL) + ak_server_core --> cache(Redis) + ak_worker(Background Worker) --> db(PostgreSQL) + ak_worker(Background Worker) --> cache(Redis) +``` + +### Server + +The server container consists of two sub-components, the actual server itself and the embedded outpost. Incoming requests to the server container(s) are routed by a lightweight router to either the _Core_ server or the embedded outpost. This router also handles requests for any static assets such as JavaScript and CSS files. + +#### Core + +The core sub-component handles most of authentik's logic, such as API requests, flow executions, any kind of SSO requests, etc. + +#### Embedded outpost + +Similar to [other outposts](../outposts/index.mdx), this outposts allows using [Proxy providers](../providers/proxy/index.md) without deploying a separate outpost. + +#### Persistence + +- `/media` is used to store icons and such, but not required, and if not mounted, authentik will allow you to set a URL to icons in place of a file upload + +### Background Worker + +This container executes background tasks, such as sending emails, the event notification system, and everything you can see on the _System Tasks_ page in the frontend. + +#### Persistence + +- `/certs` is used for authentik to import external certs, which in most cases shouldn't be used for SAML, but rather if you use authentik without a reverse proxy, this can be used for example for the [Let's Encrypt integration](../core/certificates.md#lets-encrypt) +- `/templates` is used for [custom email templates](../flow/stages/email/index.mdx#custom-templates), and as with the other ones fully optional + +### PostgreSQL + +authentik uses PostgreSQL to store all of its configuration and other data (excluding uploaded files). + +#### Persistence + +- `/var/lib/postgresql/data` is used to store the PostgreSQL database + +On Kubernetes, with the default Helm chart and using the packaged PostgreSQL sub-chart, persistent data is stored in a PVC. + +### Redis + +authentik uses Redis as a message-queue and a cache. Data in Redis is not required to be persistent, however you should be aware that restarting Redis will cause the loss of all sessions. + +#### Persistence + +- `/data` is used to store the Redis data + +On Kubernetes, with the default Helm chart and using the packaged Redis sub-chart, persistent data is stored in a PVC. diff --git a/website/docs/installation/docker-compose.md b/website/docs/installation/docker-compose.md index 10b45b7ab..2cadeb41f 100644 --- a/website/docs/installation/docker-compose.md +++ b/website/docs/installation/docker-compose.md @@ -71,6 +71,13 @@ See [Configuration](../installation/configuration) to change the internal ports. ## Startup +:::warning +The server assumes to have local timezone as UTC. +All internals are handled in UTC; whenever a time is displayed to the user in UI, the time shown is localized. +Do not update or mount `/etc/timezone` or `/etc/localtime` in the authentik containers. +This will not give any advantages. It will cause problems with OAuth and SAML authentication, e.g. [see this GitHub issue](https://github.com/goauthentik/authentik/issues/3005). +::: + Afterwards, run these commands to finish: ```shell @@ -85,28 +92,3 @@ By default, authentik is reachable (by default) on port 9000 (HTTP) and port 944 To start the initial setup, navigate to `https://:9000/if/flow/initial-setup/`. There you are prompted to set a password for the akadmin user (the default user). - -## Explanation - -:::warning -The server assumes to have local timezone as UTC. -All internals are handled in UTC; whenever a time is displayed to the user in UI it gets localized. -Do not update or mount `/etc/timezone` or `/etc/localtime` in the authentik containers. -This will not give any advantages. -On the contrary, it will cause problems with OAuth and SAML authentication, -e.g. [see this GitHub issue](https://github.com/goauthentik/authentik/issues/3005). -::: - -The Docker-Compose project contains the following containers: - -- server - - This is the backend service, which does all the logic, plus runs the API and the SSO functionality. It also runs the frontend, hosts the JS/CSS files, and serves the files you've uploaded for icons/etc. - -- worker - - This container executes background tasks, everything you can see on the _System Tasks_ page in the frontend. - -- redis (for cache) - -- postgresql (default database) diff --git a/website/sidebars.js b/website/sidebars.js index bcae7d1f4..240331e3f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -33,6 +33,7 @@ module.exports = { "core/tenants", "core/certificates", "core/geoip", + "core/architecture", ], }, {