From f7ccdcbc6d5d13f14bb906ce48641a186bd9e06f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Mon, 22 Apr 2024 23:00:18 +0200 Subject: [PATCH] Split authentication into its own section --- docs/authentication.md | 4 ++-- .../basic_auth.md | 2 +- .../cloudflare.md | 2 +- .../custom_auth.md | 2 +- .../google_iap.md | 2 +- .../tailscale.md | 2 +- .../teleport.md | 2 +- docs/deployment/clustering.md | 21 +++++++++++++++++++ docs/deployment/docker.md | 20 +----------------- mix.exs | 20 ++++++++++-------- 10 files changed, 41 insertions(+), 36 deletions(-) rename docs/{deployment => authentication}/basic_auth.md (97%) rename docs/{deployment => authentication}/cloudflare.md (97%) rename docs/{deployment => authentication}/custom_auth.md (98%) rename docs/{deployment => authentication}/google_iap.md (98%) rename docs/{deployment => authentication}/tailscale.md (98%) rename docs/{deployment => authentication}/teleport.md (97%) create mode 100644 docs/deployment/clustering.md diff --git a/docs/authentication.md b/docs/authentication.md index 10b5fbb40..d1f9979ff 100644 --- a/docs/authentication.md +++ b/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. diff --git a/docs/deployment/basic_auth.md b/docs/authentication/basic_auth.md similarity index 97% rename from docs/deployment/basic_auth.md rename to docs/authentication/basic_auth.md index cfd1054f9..64bebe3fe 100644 --- a/docs/deployment/basic_auth.md +++ b/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. diff --git a/docs/deployment/cloudflare.md b/docs/authentication/cloudflare.md similarity index 97% rename from docs/deployment/cloudflare.md rename to docs/authentication/cloudflare.md index b2e60b891..a985f8d0d 100644 --- a/docs/deployment/cloudflare.md +++ b/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. diff --git a/docs/deployment/custom_auth.md b/docs/authentication/custom_auth.md similarity index 98% rename from docs/deployment/custom_auth.md rename to docs/authentication/custom_auth.md index b5a034549..a3bdad435 100644 --- a/docs/deployment/custom_auth.md +++ b/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. diff --git a/docs/deployment/google_iap.md b/docs/authentication/google_iap.md similarity index 98% rename from docs/deployment/google_iap.md rename to docs/authentication/google_iap.md index 380b1db04..ff75856cd 100644 --- a/docs/deployment/google_iap.md +++ b/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. diff --git a/docs/deployment/tailscale.md b/docs/authentication/tailscale.md similarity index 98% rename from docs/deployment/tailscale.md rename to docs/authentication/tailscale.md index edba5e73d..4b4936b02 100644 --- a/docs/deployment/tailscale.md +++ b/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. diff --git a/docs/deployment/teleport.md b/docs/authentication/teleport.md similarity index 97% rename from docs/deployment/teleport.md rename to docs/authentication/teleport.md index a2101cd6a..17f5b03ce 100644 --- a/docs/deployment/teleport.md +++ b/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. diff --git a/docs/deployment/clustering.md b/docs/deployment/clustering.md new file mode 100644 index 000000000..c559ebe59 --- /dev/null +++ b/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"` diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index dd08a6936..30299b026 100644 --- a/docs/deployment/docker.md +++ b/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"` diff --git a/mix.exs b/mix.exs index 6002def58..ce82acd21 100644 --- a/mix.exs +++ b/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