diff --git a/docs/content/en/integration/deployment/docker.md b/docs/content/en/integration/deployment/docker.md index d1fe04032..42109751f 100644 --- a/docs/content/en/integration/deployment/docker.md +++ b/docs/content/en/integration/deployment/docker.md @@ -54,7 +54,9 @@ It expects the following: Use this [Standalone Example](#standalone-example) if you want to use [docker secrets](https://docs.docker.com/engine/swarm/secrets/). +{{< details "docker-compose.yml" >}} ```yaml +--- version: "3.8" secrets: JWT_SECRET: @@ -87,14 +89,18 @@ networks: net: external: true name: net +... ``` +{{< /details >}} #### Using a Secrets Volume Use this [Standalone Example](#standalone-example) if you want to use a standard [docker volume](https://docs.docker.com/storage/volumes/) or bind mount for your secrets. +{{< details "docker-compose.yml" >}} ```yaml +--- version: "3.8" services: authelia: @@ -119,6 +125,8 @@ networks: external: true name: net ``` +... +{{< /details >}} ### Bundles @@ -184,7 +192,9 @@ The example below includes the additional `ports` option which must be added in [Standalone Example](#standalone-example) above. The example allows *Authelia* to be communicated with over the localhost IP address `127.0.0.1` on port `9091`. You need to adjust this to your specific needs. +{{< details "docker-compose.yml" >}} ```yaml +--- services: authelia: container_name: authelia @@ -197,7 +207,9 @@ services: - 9091 ports: - "127.0.0.1:9091:9091" +... ``` +{{< /details >}} [Docker]: https://docker.com [Docker Compose]: https://docs.docker.com/compose/ diff --git a/docs/content/en/integration/kubernetes/introduction/index.md b/docs/content/en/integration/kubernetes/introduction.md similarity index 95% rename from docs/content/en/integration/kubernetes/introduction/index.md rename to docs/content/en/integration/kubernetes/introduction.md index 675ecf770..e9bd8dbc5 100644 --- a/docs/content/en/integration/kubernetes/introduction/index.md +++ b/docs/content/en/integration/kubernetes/introduction.md @@ -14,7 +14,7 @@ aliases: - /i/k8s --- -{{< figure src="kubernetes.png" alt="Kubernetes" width="100" style="padding-right: 10px" >}} +{{< figure src="/images/logos/kubernetes.png" alt="Kubernetes" width="100" style="padding-right: 10px" >}} ## UNDER CONSTRUCTION @@ -63,9 +63,6 @@ spec: ... ``` -## Secrets - - ## FAQ ### RAM usage diff --git a/docs/content/en/integration/kubernetes/introduction/kubernetes.png b/docs/content/en/integration/kubernetes/introduction/kubernetes.png deleted file mode 100644 index 5e2b1ab75..000000000 Binary files a/docs/content/en/integration/kubernetes/introduction/kubernetes.png and /dev/null differ diff --git a/docs/content/en/integration/kubernetes/secrets.md b/docs/content/en/integration/kubernetes/secrets.md index 59fcec0ef..ec035bdfe 100644 --- a/docs/content/en/integration/kubernetes/secrets.md +++ b/docs/content/en/integration/kubernetes/secrets.md @@ -40,6 +40,7 @@ can manually create a secret like this with `kubectl apply -f`. ##### secret.yaml +{{< details "secret.yml" >}} ```yaml --- kind: Secret @@ -97,10 +98,13 @@ stringData: -----END RSA PRIVATE KEY----- ... ``` +{{< /details >}} + ##### Base64 Data Example This is the same manifest as above but encoded in base64. +{{< details "secret.yml" >}} ```yaml --- kind: Secret @@ -122,14 +126,15 @@ data: STORAGE_PASSWORD: Tk1IZjlaN0M1VVFZdUtLZ2g5QkpUS2VjY29adDZjNjQ3RlFxc0VIaGthcGtrbmRQa1B3M2Q4Ym52a3FMZ2laNQ== ... ``` +{{< /details >}} + ### Kustomize The following example is a [Kustomize](https://kustomize.io/) example which can be utilized with `kubectl apply -k`. The files listed in the `secretGenerator` section of the `kustomization.yaml` must exist and contain the contents of your desired secret value. -##### kustomization.yaml - +{{< details "kustomization.yaml" >}} ```yaml --- generatorOptions: @@ -153,6 +158,7 @@ secretGenerator: - STORAGE_PASSWORD ... ``` +{{< /details >}} ## Usage @@ -162,6 +168,7 @@ details. The example is an excerpt for a manifest which can mount volumes. Examples of these are the [Pod], [Deployment], [StatefulSet], and [DaemonSet]. +{{< details "deployment.yml" >}} ```yaml --- spec: @@ -221,6 +228,7 @@ spec: path: STORAGE_PASSWORD ... ``` +{{< /details >}} [Kubernetes]: https://kubernetes.io/ [Pod]: https://kubernetes.io/docs/concepts/workloads/pods/ diff --git a/docs/content/en/integration/kubernetes/traefik-ingress.md b/docs/content/en/integration/kubernetes/traefik-ingress.md index 654863629..4dc9f30ff 100644 --- a/docs/content/en/integration/kubernetes/traefik-ingress.md +++ b/docs/content/en/integration/kubernetes/traefik-ingress.md @@ -45,7 +45,9 @@ configured it to be served on the URL `https://auth.example.com` and there is a `authelia` in the `default` namespace with TCP port `80` configured to route to the Authelia pod's HTTP port and that your cluster is configured with the default DNS domain name of `cluster.local`. +{{< details "middleware.yml" >}} ```yaml +--- apiVersion: traefik.containo.us/v1alpha1 kind: Middleware metadata: @@ -63,7 +65,9 @@ spec: - Remote-Name - Remote-Email - Remote-Groups +... ``` +{{< /details >}} ## Ingress @@ -71,7 +75,9 @@ This is an example Ingress manifest which uses the above [Middleware](#middlewar application you wish to serve on `https://app.example.com` and there is a Kubernetes Service with the name `app` in the `default` namespace with TCP port `80` configured to route to the application pod's HTTP port. +{{< details "ingress.yml" >}} ```yaml +--- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: @@ -93,7 +99,9 @@ spec: name: app port: number: 80 +... ``` +{{< /details >}} ## IngressRoute @@ -101,7 +109,9 @@ This is an example IngressRoute manifest which uses the above [Middleware](#midd application you wish to serve on `https://app.example.com` and there is a Kubernetes Service with the name `app` in the `default` namespace with TCP port `80` configured to route to the application pod's HTTP port. +{{< details "ingressRoute.yml" >}} ```yaml +--- apiVersion: traefik.containo.us/v1alpha1 kind: IngressRoute metadata: @@ -124,7 +134,9 @@ spec: scheme: http strategy: RoundRobin weight: 10 +... ``` +{{< /details >}} [Traefik Kubernetes Ingress]: https://doc.traefik.io/traefik/providers/kubernetes-ingress/ [Traefik Kubernetes CRD]: https://doc.traefik.io/traefik/providers/kubernetes-crd/ diff --git a/docs/content/en/integration/proxies/caddy.md b/docs/content/en/integration/proxies/caddy.md index 220136c06..55b2e502a 100644 --- a/docs/content/en/integration/proxies/caddy.md +++ b/docs/content/en/integration/proxies/caddy.md @@ -78,8 +78,7 @@ support to ensure the basic example covers your use case in a secure way. #### Subdomain -##### Caddyfile - +{{< details "Caddyfile" >}} ```caddyfile ## It is important to read the following document before enabling this section: ## https://www.authelia.com/integration/proxies/caddy/#forwarded-header-trust#trusted-proxies @@ -111,11 +110,11 @@ nextcloud.example.com { } } ``` +{{< /details >}} #### Subpath -##### Caddyfile - +{{< details "Caddyfile" >}} ```caddyfile ## It is important to read the following document before enabling this section: ## https://www.authelia.com/integration/proxies/caddy/#forwarded-header-trust#trusted-proxies @@ -151,7 +150,7 @@ example.com { } } ``` - +{{< /details >}} ### Advanced example The advanced example allows for more flexible customization, however the [basic example](#basic-examples) should be @@ -159,8 +158,7 @@ preferred in *most* situations. If you are unsure of what you're doing please do *__Important:__ Making a mistake when configuring the advanced example could lead to authentication bypass or errors.* -##### Caddyfile - +{{< details "Caddyfile" >}} ```caddyfile ## It is important to read the following document before enabling this section: ## https://www.authelia.com/integration/proxies/caddy/#forwarded-header-trust#trusted-proxies @@ -209,6 +207,7 @@ nextcloud.example.com { } } ``` +{{< /details >}} ## See Also diff --git a/docs/content/en/integration/proxies/nginx.md b/docs/content/en/integration/proxies/nginx.md index 6508bca85..3a195e380 100644 --- a/docs/content/en/integration/proxies/nginx.md +++ b/docs/content/en/integration/proxies/nginx.md @@ -74,10 +74,7 @@ This example is for using the __Authelia__ portal redirection flow on a specific files exist in the `/config/nginx/` directory. The `/config/nginx/ssl.conf` snippet is expected to have the configuration for TLS or SSL but is not included as part of the examples. -#### Authelia Portal - -##### auth.example.com.conf - +{{< details "Authelia Portal (auth.example.com.conf)" >}} ```nginx server { listen 80; @@ -100,11 +97,9 @@ server { } } ``` +{{< /details >}} -#### Protected Endpoint - -##### nextcloud.example.com.conf - +{{< details "Protected Endpoint (nextcloud.example.com.conf)" >}} ```nginx server { listen 80; @@ -129,6 +124,7 @@ server { } } ``` +{{< /details >}} ### HTTP Basic Authentication Example @@ -138,10 +134,10 @@ to have the [authelia-location-basic.conf](#authelia-location-basicconf), example these files exist in the `/config/nginx/` directory. The `/config/nginx/ssl.conf` snippet is expected to have the configuration for TLS or SSL but is not included as part of the examples. -The [Authelia Portal](#authelia-portal) configuration can be reused for this example as such it isn't repeated. - -#### HTTP Basic Authentication Protected Endpoint +The Authelia Portal file from the [Standard Example](#standard-example) configuration can be reused for this example as +such it isn't repeated. +{{< details "Protected Endpoint (nextcloud.example.com.conf)" >}} ```nginx server { listen 80; @@ -166,6 +162,7 @@ server { } } ``` +{{< /details >}} ### Supporting Configuration Snippets @@ -181,6 +178,7 @@ The following is an example `proxy.conf`. The important directives include the ` [Trusted Proxies](#trusted-proxies) section to understand, or set the `X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Forwarded-Uri`, and `X-Forwarded-For` headers. +{{< details "proxy.conf" >}} ```nginx ## Headers proxy_set_header Host $host; @@ -217,11 +215,14 @@ proxy_read_timeout 360; proxy_send_timeout 360; proxy_connect_timeout 360; ``` +{{< /details >}} #### authelia-location.conf *The following snippet is used within the `server` block of a virtual host as a supporting endpoint used by `auth_request` and is paired with [authelia-authrequest.conf](#authelia-authrequestconf).* + +{{< details "authelia-location.conf" >}} ```nginx set $upstream_authelia http://authelia:9091/api/verify; @@ -259,12 +260,14 @@ location /authelia { proxy_connect_timeout 240; } ``` +{{< /details >}} #### authelia-authrequest.conf *The following snippet is used within a `location` block of a virtual host which uses the appropriate location block and is paired with [authelia-location.conf](#authelia-locationconf).* +{{< details "authelia-authrequest.conf" >}} ```nginx ## Send a subrequest to Authelia to verify if the user is authenticated and has permission to access the resource. auth_request /authelia; @@ -287,6 +290,7 @@ proxy_set_header Remote-Email $email; ## If the subreqest returns 200 pass to the backend, if the subrequest returns 401 redirect to the portal. error_page 401 =302 https://auth.example.com/?rd=$target_url; ``` +{{< /details >}} #### authelia-location-basic.conf @@ -296,6 +300,7 @@ snippet is rarely required. It's only used if you want to only allow [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-location.conf](#authelia-locationconf) instead.* +{{< details "authelia-location-basic.conf" >}} ```nginx set $upstream_authelia http://authelia:9091/api/verify?auth=basic; @@ -333,6 +338,7 @@ location /authelia-basic { proxy_connect_timeout 240; } ``` +{{< /details >}} #### authelia-authrequest-basic.conf @@ -342,6 +348,7 @@ required. It's only used if you want to only allow [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-authrequest.conf](#authelia-authrequestconf) instead.* +{{< details "authelia-authrequest-basic.conf" >}} ```nginx ## Send a subrequest to Authelia to verify if the user is authenticated and has permission to access the resource. auth_request /authelia-basic; @@ -361,6 +368,7 @@ proxy_set_header Remote-Groups $groups; proxy_set_header Remote-Name $name; proxy_set_header Remote-Email $email; ``` +{{< /details >}} #### authelia-location-detect.conf @@ -370,6 +378,7 @@ snippet is rarely required. It's only used if you want to conditionally require [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-location.conf](#authelia-locationconf) instead.* +{{< details "authelia-location-detect.conf" >}} ```nginx include /config/nginx/authelia-location.conf; @@ -398,6 +407,7 @@ location /authelia-detect { return 302 https://auth.example.com/$is_args$args; } ``` +{{< /details >}} #### authelia-authrequest-detect.conf @@ -407,6 +417,7 @@ required. It's only used if you want to conditionally require [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) for a particular endpoint. It's recommended to use [authelia-authrequest.conf](#authelia-authrequestconf) instead.* +{{< details "authelia-authrequest-detect.conf" >}} ```nginx ## Send a subrequest to Authelia to verify if the user is authenticated and has permission to access the resource. auth_request /authelia; @@ -429,6 +440,7 @@ proxy_set_header Remote-Email $email; ## If the subreqest returns 200 pass to the backend, if the subrequest returns 401 redirect to the portal. error_page 401 =302 /authelia-detect?rd=$target_url; ``` +{{< /details >}} ## See Also diff --git a/docs/content/en/integration/proxies/traefik.md b/docs/content/en/integration/proxies/traefik.md index 70f0b978a..a1c40d9bb 100644 --- a/docs/content/en/integration/proxies/traefik.md +++ b/docs/content/en/integration/proxies/traefik.md @@ -80,9 +80,9 @@ Please ensure that you also setup the respective [ACME configuration](https://do This is an example configuration using [docker compose] labels: -##### docker-compose.yml - +{{< details "docker-compose.yml" >}} ```yaml +--- version: "3.8" networks: net: @@ -199,7 +199,9 @@ services: - 'traefik.http.routers.heimdall.entryPoints=https' - 'traefik.http.routers.heimdall.tls=true' - 'traefik.http.routers.heimdall.middlewares=authelia-basic@docker' +... ``` +{{< /details >}} ### YAML @@ -215,9 +217,9 @@ This example uses a `docker-compose.yml` similar to the one above however it has all `forwardAuth` middlewares, adjusting the `authelia` router in the `http.routers` section to use the `authelia-net@docker` service, and commenting the `authelia` service in the `http.service` section. -##### docker-compose.yml - +{{< details "docker-compose.yml" >}} ```yaml +--- version: "3.8" networks: net: @@ -319,16 +321,17 @@ services: TZ: "Australia/Melbourne" labels: - "traefik.enable=true" - +... ``` - -##### traefik.yml +{{< /details >}} This file is part of the dynamic configuration and should have the path `${PWD}/data/traefik/config/dynamic/traefik.yml`. Please see the [Traefik] service and the volume that mounts the `${PWD}/data/traefik/config` in the docker compose above. +{{< details "traefik.yml" >}} ```yaml +--- entryPoints: web: proxyProtocol: @@ -462,7 +465,9 @@ http: keyFile: /certificates/traefik.private.pem rootCAs: - /certificates/ca.public.crt +... ``` +{{< /details >}} ## FAQ