website/docs: include OS-specific docker-compose install instructions + minor fixes (#8975)
* docs: include OS-specific docker-compose install instructions + minor fixes * Update website/docs/installation/kubernetes.md Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> * Update website/docs/installation/configuration.mdx Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> * Update website/docs/installation/configuration.mdx Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com> Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> * Update configuration.mdx HTTPS description clarification Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> * Update certificates.md for more clarity, simpler language Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> * Update kubernetes.md . > ; Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> * Update configuration.mdx clarifications Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> * bye windows * take old config env vars back out --------- Signed-off-by: Fletcher Heisler <fheisler@users.noreply.github.com> Co-authored-by: Fletcher Heisler <fletcher@goauthentik.io> Co-authored-by: Tana M Berry <tanamarieberry@yahoo.com>
This commit is contained in:
Fletcher Heisler
@ -110,7 +110,7 @@ To check if your config has been applied correctly, you can run the following co
|
||||
## Broker Settings
|
||||
|
||||
- `AUTHENTIK_BROKER__URL`: Broker configuration URL, defaults to Redis using [the respective settings](#redis-settings)
|
||||
- `AUTHENTIK_BROKER__TRANSPORT_OPTIONS`: Base64 encoded broker transport options
|
||||
- `AUTHENTIK_BROKER__TRANSPORT_OPTIONS`: Base64-encoded broker transport options
|
||||
|
||||
:::info
|
||||
`AUTHENTIK_REDIS__CACHE_TIMEOUT_REPUTATION` only applies to the cache expiry, see [`AUTHENTIK_REPUTATION__EXPIRY`](#authentik_reputation__expiry) to control how long reputation is persisted for.
|
||||
@ -144,19 +144,19 @@ These settings affect where media files are stored. Those files include applicat
|
||||
- `AUTHENTIK_STORAGE__MEDIA__S3__SECURITY_TOKEN`: Security token to authenticate to S3. May be omitted. Supports hot-reloading.
|
||||
- `AUTHENTIK_STORAGE__MEDIA__S3__BUCKET_NAME`: Name of the bucket to use to store files.
|
||||
- `AUTHENTIK_STORAGE__MEDIA__S3__CUSTOM_DOMAIN`: Domain to use to create URLs for users. Mainly useful for non-AWS providers. May include a port. Must include the bucket. Example: `s3.company:8080/authentik-media`.
|
||||
- `AUTHENTIK_STORAGE__MEDIA__S3__SECURE_URLS`: Whether URLS created for users use `http` or `https`. Defaults to `true`.
|
||||
- `AUTHENTIK_STORAGE__MEDIA__S3__SECURE_URLS`: Whether URLs created use HTTPS (set to `true` by default) or HTTP.
|
||||
|
||||
## authentik Settings
|
||||
|
||||
### `AUTHENTIK_SECRET_KEY`
|
||||
|
||||
Secret key used for cookie signing and unique user IDs, don't change this after the first install.
|
||||
Secret key used for cookie signing and unique user IDs. Do not change this after the first install.
|
||||
|
||||
### `AUTHENTIK_LOG_LEVEL`
|
||||
|
||||
Log level for the server and worker containers. Possible values: debug, info, warning, error
|
||||
Log level for the server and worker containers. Possible values: `debug`, `info`, `warning`, `error`.
|
||||
|
||||
Starting with 2021.12.3, you can also set the log level to _trace_. This has no affect on the core authentik server, but shows additional messages for the embedded outpost.
|
||||
Starting with 2021.12.3, you can also set the log level to `trace`. This has no effect on the core authentik server, but shows additional messages for the embedded outpost.
|
||||
|
||||
:::danger
|
||||
Setting the log level to `trace` will include sensitive details in logs, so it shouldn't be used in most cases.
|
||||
@ -188,7 +188,7 @@ Disable the inbuilt update-checker. Defaults to `false`.
|
||||
|
||||
Enable error reporting. Defaults to `false`.
|
||||
|
||||
Error reports are sent to https://sentry.io, and are used for debugging and general feedback. Anonymous performance data is also sent.
|
||||
Error reports are sent to https://sentry.io and are used for debugging and general feedback. Anonymous performance data is also sent.
|
||||
|
||||
- `AUTHENTIK_ERROR_REPORTING__SENTRY_DSN`
|
||||
|
||||
@ -202,8 +202,7 @@ Disable the inbuilt update-checker. Defaults to `false`.
|
||||
|
||||
The environment tag associated with all data sent to Sentry. Defaults to `customer`.
|
||||
|
||||
When error reporting has been enabled to aid in debugging issues, this should be set to a unique
|
||||
value, such as an e-mail address.
|
||||
When error reporting has been enabled to aid in debugging issues, this should be set to a unique value, such as an email address.
|
||||
|
||||
- `AUTHENTIK_ERROR_REPORTING__SEND_PII`
|
||||
|
||||
@ -326,7 +325,7 @@ Requires authentik 2022.9
|
||||
Configure how many gunicorn worker processes should be started (see https://docs.gunicorn.org/en/stable/design.html).
|
||||
|
||||
If running in Kubernetes, the default value is set to 2 and should in most cases not be changed, as scaling can be done with multiple pods running the web server.
|
||||
Otherwise, authentik will use 1 worker for each 4 CPU cores + 1 as a value below 2 workers is not recommended.
|
||||
Otherwise, authentik will use 1 worker for each 4 CPU cores + 1. A value below 2 workers is not recommended.
|
||||
|
||||
### `AUTHENTIK_WEB__THREADS`
|
||||
|
||||
@ -358,7 +357,7 @@ Additional settings are configurable using the Admin interface, under **System**
|
||||
|
||||
## Custom python settings
|
||||
|
||||
To modify additional settings further than the options above allow, you can create a custom python file and mount it to `/data/user_settings.py`. This file will be loaded on startup by both the server and the worker. All default settings are [here](https://github.com/goauthentik/authentik/blob/main/authentik/root/settings.py)
|
||||
To modify additional settings further than the options above allow, you can create a custom Python file and mount it to `/data/user_settings.py`. This file will be loaded on startup by both the server and the worker. All default settings are [here](https://github.com/goauthentik/authentik/blob/main/authentik/root/settings.py)
|
||||
|
||||
:::caution
|
||||
Using these custom settings is not supported and can prevent your authentik instance from starting. Use with caution.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
title: Docker Compose installation
|
||||
---
|
||||
|
||||
This installation method is for test-setups and small-scale production setups.
|
||||
This installation method is for test setups and small-scale production setups.
|
||||
|
||||
## Requirements
|
||||
|
||||
@ -12,32 +12,51 @@ This installation method is for test-setups and small-scale production setups.
|
||||
|
||||
## Video
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/O1qUbrk4Yc8?si=HiSBjmJYhE_oJhB1&start=22" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.youtube.com/embed/O1qUbrk4Yc8?si=HiSBjmJYhE_oJhB1&start=22"
|
||||
title="YouTube video player"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
## Preparation
|
||||
|
||||
To download the latest `docker-compose.yml` open your terminal and navigate to the directory of your choice.
|
||||
Run the following command:
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
{/* prettier-ignore */}
|
||||
<Tabs groupId="OS">
|
||||
<TabItem value="Linux" label="Linux" default>
|
||||
```shell
|
||||
wget https://goauthentik.io/docker-compose.yml
|
||||
```
|
||||
</TabItem>
|
||||
<TabItem value="MacOS" label="MacOS">
|
||||
```shell
|
||||
curl -O https://goauthentik.io/docker-compose.yml
|
||||
```
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
If this is a fresh authentik installation, you need to generate a password and a secret key. Use a secure password generator of your choice such as pwgen, or you can use `openssl` as below.
|
||||
|
||||
Run the following commands to generate a password and secret key and write them to your `.env` file:
|
||||
|
||||
{/* prettier-ignore */}
|
||||
```shell
|
||||
wget https://goauthentik.io/docker-compose.yml
|
||||
echo "PG_PASS=$(openssl rand -base64 36)" >> .env
|
||||
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 36)" >> .env
|
||||
```
|
||||
|
||||
If this is a fresh authentik installation, you need to generate a password and a secret key. If you don't already have a password generator installed, you can run this command to install **pwgen**, a popular generator:
|
||||
|
||||
```shell
|
||||
# You can also use openssl instead: `openssl rand -base64 36`
|
||||
sudo apt-get install -y pwgen
|
||||
```
|
||||
|
||||
Next, run the following commands to generate a password and secret key and write them to your `.env` file:
|
||||
|
||||
```shell
|
||||
echo "PG_PASS=$(pwgen -s 40 1)" >> .env
|
||||
echo "AUTHENTIK_SECRET_KEY=$(pwgen -s 50 1)" >> .env
|
||||
# Because of a PostgreSQL limitation, only passwords up to 99 chars are supported
|
||||
# See https://www.postgresql.org/message-id/09512C4F-8CB9-4021-B455-EF4C4F0D55A0@amazon.com
|
||||
```
|
||||
:::info
|
||||
Because of a PostgreSQL limitation, only passwords up to 99 chars are supported. See: https://www.postgresql.org/message-id/09512C4F-8CB9-4021-B455-EF4C4F0D55A0@amazon.com
|
||||
:::
|
||||
|
||||
To enable error reporting, run the following command:
|
||||
|
||||
@ -87,7 +106,7 @@ Do not update or mount `/etc/timezone` or `/etc/localtime` in the authentik cont
|
||||
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:
|
||||
Afterward, run these commands to finish:
|
||||
|
||||
```shell
|
||||
docker compose pull
|
||||
@ -98,6 +117,6 @@ The `docker-compose.yml` file statically references the latest version available
|
||||
|
||||
To start the initial setup, navigate to `http://<your server's IP or hostname>:9000/if/flow/initial-setup/`.
|
||||
|
||||
There you are prompted to set a password for the akadmin user (the default user).
|
||||
There you are prompted to set a password for the `akadmin` user (the default user).
|
||||
|
||||
An explanation about what each service in the docker compose file does, see [Architecture](../core/architecture.md).
|
||||
For an explanation about what each service in the docker compose file does, see [Architecture](../core/architecture.md).
|
||||
@ -32,7 +32,7 @@ Create a `values.yaml` file with a minimum of these settings:
|
||||
|
||||
```yaml
|
||||
authentik:
|
||||
secret_key: "PleaseGenerateA50CharKey"
|
||||
secret_key: "PleaseGenerateASecureKey"
|
||||
# This sends anonymous usage-data, stack traces on errors and
|
||||
# performance data to sentry.io, and is fully opt-in
|
||||
error_reporting:
|
||||
@ -60,7 +60,7 @@ See all configurable values on [ArtifactHub](https://artifacthub.io/packages/hel
|
||||
|
||||
### Install authentik Helm Chart
|
||||
|
||||
Now, execute the following commands to install authentik
|
||||
Now, execute the following commands to install authentik:
|
||||
|
||||
```
|
||||
helm repo add authentik https://charts.goauthentik.io
|
||||
@ -72,7 +72,7 @@ During the installation process, the database migrations will be applied automat
|
||||
|
||||
### Accessing authentik
|
||||
|
||||
Once the installation is complete, access authentik at `https://<ingress-host-name>/if/flow/initial-setup/`. Here, you can set a password for the default akadmin user.
|
||||
After the installation is complete, access authentik at `https://<ingress-host-name>/if/flow/initial-setup/`. Here, you can set a password for the default `akadmin` user.
|
||||
|
||||
### Optional step: Configure global email credentials
|
||||
|
||||
@ -87,17 +87,17 @@ email:
|
||||
# -- SMTP Server emails are sent from, fully optional
|
||||
host: ""
|
||||
port: 587
|
||||
# -- SMTP credentials, when left empty, no authentication will be done
|
||||
# -- SMTP credentials. When left empty, no authentication will be done.
|
||||
username: ""
|
||||
# -- SMTP credentials, when left empty, no authentication will be done
|
||||
# -- SMTP credentials. When left empty, no authentication will be done.
|
||||
password: ""
|
||||
# -- Enable either use_tls or use_ssl, they can't be enabled at the same time.
|
||||
# -- Enable either use_tls or use_ssl. They can't be enabled at the same time.
|
||||
use_tls: false
|
||||
# -- Enable either use_tls or use_ssl, they can't be enabled at the same time.
|
||||
# -- Enable either use_tls or use_ssl. They can't be enabled at the same time.
|
||||
use_ssl: false
|
||||
# -- Connection timeout
|
||||
# -- Connection timeout in seconds
|
||||
timeout: 30
|
||||
# -- Email from address, can either be in the format "foo@bar.baz" or "authentik <foo@bar.baz>"
|
||||
# -- Email 'from' address can either be in the format "foo@bar.baz" or "authentik <foo@bar.baz>"
|
||||
from: ""
|
||||
```
|
||||
|
||||
|
||||
@ -2,11 +2,11 @@
|
||||
title: Monitoring
|
||||
---
|
||||
|
||||
authentik can be easily monitored multiple ways.
|
||||
authentik can be easily monitored in multiple ways.
|
||||
|
||||
## Server monitoring
|
||||
|
||||
Configure your monitoring software to send requests to `/-/health/live/`, which will return a HTTP 204 response as long as authentik is running. You can also send HTTP requests to `/-/health/ready/`, which will return HTTP 204 if both PostgreSQL and Redis connections can be/have been established correctly.
|
||||
Configure your monitoring software to send requests to `/-/health/live/`, which will return a `HTTP 204` response as long as authentik is running. You can also send HTTP requests to `/-/health/ready/`, which will return `HTTP 204` if both PostgreSQL and Redis connections can be/have been established correctly.
|
||||
|
||||
## Worker monitoring
|
||||
|
||||
@ -14,11 +14,11 @@ The worker container can be monitored by running `ak healthcheck` in the worker
|
||||
|
||||
## Outpost monitoring
|
||||
|
||||
Both kinds of outpost (proxy and LDAP) listen on a separate port (9300), and can be monitored by sending HTTP requests to `/outpost.goauthentik.io/ping`.
|
||||
Both kinds of outpost (proxy and LDAP) listen on a separate port (9300) and can be monitored by sending HTTP requests to `/outpost.goauthentik.io/ping`.
|
||||
|
||||
---
|
||||
|
||||
Both docker-compose and Kubernetes deployments use these methods by default to determine when authentik is ready after starting, and to only route traffic to healthy instances, and unhealthy instances are restarted
|
||||
Both Docker Compose and Kubernetes deployments use these methods by default to determine when authentik is ready after starting, and to only route traffic to healthy instances; unhealthy instances are restarted.
|
||||
|
||||
## Metrics
|
||||
|
||||
|
||||
@ -6,9 +6,9 @@ title: Reverse-proxy
|
||||
Since authentik uses WebSockets to communicate with Outposts, it does not support HTTP/1.0 reverse-proxies. The HTTP/1.0 specification does not officially support WebSockets or protocol upgrades, though some clients may allow it.
|
||||
:::
|
||||
|
||||
If you want to access authentik behind a reverse-proxy, there are a few headers that must be passed upstream:
|
||||
If you want to access authentik behind a reverse proxy, there are a few headers that must be passed upstream:
|
||||
|
||||
- `X-Forwarded-Proto`: Tells authentik and Proxy Providers if they are being served over a HTTPS connection.
|
||||
- `X-Forwarded-Proto`: Tells authentik and Proxy Providers if they are being served over an HTTPS connection.
|
||||
- `X-Forwarded-For`: Without this, authentik will not know the IP addresses of clients.
|
||||
- `Host`: Required for various security checks, WebSocket handshake, and Outpost and Proxy Provider communication.
|
||||
- `Connection: Upgrade` and `Upgrade: WebSocket`: Required to upgrade protocols for requests to the WebSocket endpoints under HTTP/1.1.
|
||||
|
||||
@ -6,9 +6,9 @@ title: S3 storage setup
|
||||
|
||||
First, create a user on your S3 storage provider and get access credentials for S3, hereafter referred as `access_key` and `secret_key`.
|
||||
|
||||
You'll also need to know which endpoint authentik is going to use to access the S3 API, hereafter referred as `https://s3.provider`.
|
||||
You will also need to know which endpoint authentik is going to use to access the S3 API, hereafter referred as `https://s3.provider`.
|
||||
|
||||
The bucket in which authentik is going to store files is going to be called `authentik-media`. You may need to change this name depending on your S3 provider limitations. Also, we're suffixing the bucket name with `-media` as authentik currently only stores media files, but may use other buckets in the future.
|
||||
The bucket in which authentik is going to store files is going to be called `authentik-media`. You may need to change this name depending on your S3 provider limitations. Also, we are suffixing the bucket name with `-media` as authentik currently only stores media files, but may use other buckets in the future.
|
||||
|
||||
The domain used to access authentik is going to be referred to as `authentik.company`.
|
||||
|
||||
@ -18,7 +18,7 @@ You will also need the AWS CLI.
|
||||
|
||||
#### Bucket creation
|
||||
|
||||
Let's create the bucket in which authentik is going to store files:
|
||||
Create the bucket in which authentik is going to store files:
|
||||
|
||||
```bash
|
||||
AWS_ACCESS_KEY_ID=access_key AWS_SECRET_ACCESS_KEY=secret_key aws s3api --endpoint-url=https://s3.provider create-bucket --bucket=authentik-media --acl=private
|
||||
@ -30,7 +30,7 @@ The bucket ACL is set to private, although that is not strictly necessary, as an
|
||||
|
||||
#### CORS policy
|
||||
|
||||
Next, let's associate a CORS policy to the bucket, to allow the authentik web interface to show images stored in the bucket.
|
||||
Next, associate a CORS policy to the bucket to allow the authentik web interface to show images stored in the bucket.
|
||||
|
||||
First, save the following file locally as `cors.json`:
|
||||
|
||||
@ -49,7 +49,7 @@ First, save the following file locally as `cors.json`:
|
||||
|
||||
If authentik is accessed from multiple domains, you can add them to the `AllowedOrigins` list.
|
||||
|
||||
Let's apply that policy to the bucket:
|
||||
Apply that policy to the bucket:
|
||||
|
||||
```bash
|
||||
AWS_ACCESS_KEY_ID=access_key AWS_SECRET_ACCESS_KEY=secret_key aws s3api --endpoint-url=https://s3.provider put-bucket-cors --bucket=authentik-media --cors-configuration=file://cors.json
|
||||
@ -66,13 +66,13 @@ AUTHENTIK_STORAGE__MEDIA__S3__SECRET_KEY=secret_key
|
||||
AUTHENTIK_STORAGE__MEDIA__S3__BUCKET_NAME=authentik-media
|
||||
```
|
||||
|
||||
If you're using AWS S3 as your S3 provider, add the following:
|
||||
If you are using AWS S3 as your S3 provider, add the following:
|
||||
|
||||
```env
|
||||
AUTHENTIK_STORAGE__MEDIA__S3__REGION=us-east-1 # Use the region of the bucket
|
||||
```
|
||||
|
||||
If you're not using AWS S3 as your S3 provider, add the following:
|
||||
If you are not using AWS S3 as your S3 provider, add the following:
|
||||
|
||||
```env
|
||||
AUTHENTIK_STORAGE__MEDIA__S3__ENDPOINT=https://s3.provider
|
||||
@ -81,7 +81,7 @@ AUTHENTIK_STORAGE__MEDIA__S3__CUSTOM_DOMAIN=s3.provider/authentik-media
|
||||
|
||||
The `ENDPOINT` setting specifies how authentik talks to the S3 provider.
|
||||
|
||||
The `CUSTOM_DOMAIN` setting specifies how URLs are constructed to be shown on the web interface. For example, an object stored at `application-icons/application.png` with a `CUSTOM__DOMAIN` setting of `s3.provider/authentik-media` will result in a URL of `https://s3.provider/authentik-media/application-icons/application.png`. You can also use subdomains for your buckets depending on what your S3 provider offers: `authentik-media.s3.provider`. Whether HTTPS is used is controlled by the `AUTHENTIK_STORAGE__MEDIA__S3__SECURE_URLS` which defaults to true.
|
||||
The `CUSTOM_DOMAIN` setting specifies how URLs are constructed to be shown on the web interface. For example, an object stored at `application-icons/application.png` with a `CUSTOM__DOMAIN` setting of `s3.provider/authentik-media` will result in a URL of `https://s3.provider/authentik-media/application-icons/application.png`. You can also use subdomains for your buckets depending on what your S3 provider offers: `authentik-media.s3.provider`. Whether HTTPS is used is controlled by `AUTHENTIK_STORAGE__MEDIA__S3__SECURE_URLS`, which defaults to true.
|
||||
|
||||
For more control over settings, refer to the [configuration reference](./configuration.mdx#media-storage-settings)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user