Split authentication into its own section

docs/authentication.md

@@ -2,9 +2,9 @@
 
 Livebook has three levels of authentication:
 
-  * Instance authentication: this authenticates the user on all routes of your Livebook instance, including deployed notebooks and the admin section. This is done via Zero Trust Authentication and typically used when deploying Livebook to production. See the "Deployment" section on the sidebar for more information.
+  * Instance authentication: this authenticates the user on all routes of your Livebook instance, including deployed notebooks and the admin section. This is done via Zero Trust Authentication and typically used when deploying Livebook to production. See the "Authentication" section on the sidebar for more information.
 
-  * Admin authentication: this authenticates access to Livebook admin interface, where users can create, write, and manage notebooks. Both password and token authentication are provided.
+  * Admin authentication: this authenticates access to Livebook admin interface, where users can create, write, and manage notebooks. Both password and token authentication are available. See the next section for more information.
 
   * Deployed notebook authentication: additionally, when deploying notebooks as applications, each application may be password protected with a unique password. Only users authenticated as admin or with the password will be able to access them.
 

docs/authentication/basic_auth.md

@@ -1,4 +1,4 @@
-# Authentication with Basic Auth
+# Basic Auth
 
 Setting up Basic Authentication is a simple mechanism for protecting all routes of your Livebook instance with a single username-password combo. However, because this password is shared across all users, this authentication mechanism cannot be used to identity users and more robust authentication methods provided by Livebook should be preferred. Basic Authentication occurs in addition to [Livebook's authentication](../authentication.md) for deployed notebooks and admins.
 

docs/authentication/cloudflare.md

@@ -1,4 +1,4 @@
-# Authentication with Cloudflare
+# Cloudflare
 
 Setting up Cloudflare authentication will protect all routes of your Livebook instance. It is particularly useful for adding authentication to Livebook instances with deployed notebooks. Cloudflare authentication occurs in addition to [Livebook's authentication](../authentication.md) for deployed notebooks and admins.
 

docs/authentication/custom_auth.md

@@ -1,4 +1,4 @@
-# Custom authentication
+# Custom
 
 It is possible to provide custom Zero Trust Authentication (ZTA) inside Livebook's Docker images.
 

docs/authentication/google_iap.md

@@ -1,4 +1,4 @@
-# Authentication with Google IAP
+# Google IAP
 
 Setting up Google IAP authentication will protect all routes of your Livebook instance. It is particularly useful for adding authentication to Livebook instances with deployed notebooks. Google IAP authentication occurs in addition to [Livebook's authentication](../authentication.md) for deployed notebooks and admins.
 

docs/authentication/tailscale.md

@@ -1,4 +1,4 @@
-# Authentication with Tailscale
+# Tailscale
 
 Setting up Tailscale authentication will protect all routes of your Livebook instance. It is particularly useful for adding authentication to Livebook instances with deployed notebooks. Tailscale authentication occurs in addition to [Livebook's authentication](../authentication.md) for deployed notebooks and admins.
 

docs/authentication/teleport.md

@@ -1,4 +1,4 @@
-# Authentication with Teleport
+# Teleport
 
 Setting up Teleport authentication will protect all routes of your Livebook instance. It is particularly useful for adding authentication to Livebook instances with deployed notebooks. Teleport authentication occurs in addition to [Livebook's authentication](../authentication.md) for deployed notebooks and admins.
 

docs/deployment/clustering.md

@@ -0,0 +1,21 @@
+# Clustering
+
+If you plan to run several Livebook instances behind a load balancer, you need to enable clustering via the `LIVEBOOK_CLUSTER` environment variable. `LIVEBOOK_DISTRIBUTION` is automatically set to `name` if clustering is enabled.
+
+Depending on the clustering strategy of your choice, you must set additional environment variables, oftentimes, at runtime. When using the Livebook Docker image, you can create a file at `/app/user/env.sh` that exports the necessary environment variables. This file is invoked right before booting Livebook.
+
+You may set `LIVEBOOK_CLUSTER` to one of the following values.
+
+## `fly`
+
+It automatically sets up a cluster to run on Fly using DNS configuration. Behind the scenes, it sets the relevant environment variables and enables IPv6 support.
+
+## `dns:QUERY`
+
+Sets up a cluster using DNS for queries for A/AAAA records to discover new nodes. Additionally, you must additionally set the following env vars:
+
+  * `LIVEBOOK_NODE=livebook_server@IP`, where `IP` is the machine IP of each deployed node
+
+  * You must set `LIVEBOOK_SECRET_KEY_BASE` and `LIVEBOOK_COOKIE` to different random values (use `openssl rand -base64 48` to generate said values)
+
+  * If your cloud requires IPv6, also set `ERL_AFLAGS="-proto_dist inet6_tcp"`

docs/deployment/docker.md

@@ -22,7 +22,7 @@ RUN chmod 777 /data
 
 We also recommend setting the `LIVEBOOK_PASSWORD` environment variable to a secret value. If it is not set, you will find the token to access Livebook in the logs. See all other supported [environment variables](../../README.md#environment-variables) to learn more.
 
-If you want to run several Livebook instances behind a load balancer, you need to enable clustering. See the [Clustering](#clustering) section.
+If you want to run several Livebook instances behind a load balancer, you need to enable clustering. See the [Clustering](clustering.md) section.
 
 If you plan to limit access to your Livebook via a proxy, we recommend leaving the "/public" route of your instances still public. This route is used for integration with the [Livebook Badge](https://livebook.dev/badge/) and other conveniences.
 
@@ -47,21 +47,3 @@ services:
 It is possible to deploy any notebook as an application in Livebook. Inside the notebook, open up the Application pane on the sidebar (with a rocket icon), click "Deploy with Docker", and follow the required steps. You will be able to choose a Livebook image, preset clustering options, and more.
 
 If you are using [Livebook Teams](https://livebook.dev/teams/), you will also have access to airgapped notebook deployment with pre-configured Zero Trust Authentication, shared team secrets and file storages. To get started, open up Livebook, click "Add Organization" on the sidebar, and visit the "Airgapped Deployment" section of your organization.
-
-## Clustering
-
-If you plan to run several Livebook instances behind a load balancer, you need to enable clustering via the `LIVEBOOK_CLUSTER` environment variable. Depending on the strategy of your choice, you must set additional environment variables, oftentimes, at runtime. When using the Livebook Docker image, you can create a file at `/app/user/env.sh` that exports the necessary environment variables. This file is invoked right before booting Livebook. `LIVEBOOK_DISTRIBUTION` is automatically set to `name` if clustering is enabled.
-
-### `LIVEBOOK_CLUSTER=fly`
-
-It automatically sets up a cluster to run on Fly using DNS configuration. It automatically sets up the environment variables based on your Fly Application name and enables IPv6 support.
-
-### `LIVEBOOK_CLUSTER=dns:QUERY`
-
-Sets up a cluster using DNS for queries for A/AAAA records to discover new nodes. Additionally, you must additionally set the following env vars:
-
-  * `LIVEBOOK_NODE=livebook_server@IP`, where `IP` is the machine IP of each deployed node
-
-  * You must set `LIVEBOOK_SECRET_KEY_BASE` and `LIVEBOOK_COOKIE` to different random values (use `openssl rand -base64 48` to generate said values)
-
-  * If your cloud requires IPv6, also set `ERL_AFLAGS="-proto_dist inet6_tcp"`

mix.exs

@@ -28,7 +28,7 @@ defmodule Livebook.MixProject do
 
       # Docs
       homepage_url: "https://livebook.dev",
-      docs: docs()
+      docs: &docs/0
     ]
   end
 
@@ -209,7 +209,8 @@ defmodule Livebook.MixProject do
       assets: Path.expand("./docs/images"),
       groups_for_extras: [
         "Livebook Teams": Path.wildcard("docs/teams/*"),
-        Deployment: Path.wildcard("docs/deployment/*")
+        Deployment: Path.wildcard("docs/deployment/*"),
+        Authentication: Path.wildcard("docs/authentication/*")
       ]
     ]
   end
@@ -220,16 +221,17 @@ defmodule Livebook.MixProject do
       "docs/use_cases.md",
       "docs/authentication.md",
       "docs/deployment/docker.md",
+      "docs/deployment/clustering.md",
       "docs/deployment/fips.md",
-      "docs/deployment/basic_auth.md",
-      "docs/deployment/cloudflare.md",
-      "docs/deployment/google_iap.md",
-      "docs/deployment/tailscale.md",
-      "docs/deployment/teleport.md",
-      "docs/deployment/custom_auth.md",
       "docs/teams/intro_to_teams.md",
       "docs/teams/shared_secrets.md",
-      "docs/teams/shared_file_storages.md"
+      "docs/teams/shared_file_storages.md",
+      "docs/authentication/basic_auth.md",
+      "docs/authentication/cloudflare.md",
+      "docs/authentication/google_iap.md",
+      "docs/authentication/tailscale.md",
+      "docs/authentication/teleport.md",
+      "docs/authentication/custom_auth.md"
     ]
   end
 end