From 4d76c575307acaa19575a68cafb76e042e26cc55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Thu, 21 Sep 2023 11:21:50 +0200 Subject: [PATCH] Touch ups --- README.md | 9 +++---- docs/authentication.md | 20 ++++++++++++++ docs/authentication/cloudflare.md | 10 ------- docs/authentication/google_iap.md | 11 -------- docs/authentication/token_authentication.md | 8 ------ docs/deployment/cloudflare.md | 20 ++++++++++++++ docs/deployment/docker.md | 27 +++++++++++++++++++ docs/deployment/google_iap.md | 20 ++++++++++++++ .../tailscale.md | 16 ++++++++--- lib/livebook/config.ex | 14 +++------- .../live/hub/edit/team_component.ex | 9 ++++--- mix.exs | 14 +++++----- 12 files changed, 121 insertions(+), 57 deletions(-) create mode 100644 docs/authentication.md delete mode 100644 docs/authentication/cloudflare.md delete mode 100644 docs/authentication/google_iap.md delete mode 100644 docs/authentication/token_authentication.md create mode 100644 docs/deployment/cloudflare.md create mode 100644 docs/deployment/docker.md create mode 100644 docs/deployment/google_iap.md rename docs/{authentication => deployment}/tailscale.md (56%) diff --git a/README.md b/README.md index 1372566f3..e97d57259 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,7 @@ -

- - Livebook - -

+# Livebook -[![Website](https://img.shields.io/badge/-Website-%23ff87a7)](https://livebook.dev/) [![Version](https://img.shields.io/hexpm/v/livebook?color=b5a3be)](https://hex.pm/packages/livebook) +[![Website](https://img.shields.io/badge/-Website-%23ff87a7)](https://livebook.dev/) +[![Latest Version](https://img.shields.io/hexpm/v/livebook?color=b5a3be&label=Latest+version)](https://hexdocs.pm/livebook) Livebook is a web application for writing interactive and collaborative code notebooks. It features: diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 000000000..7b9dc9cb7 --- /dev/null +++ b/docs/authentication.md @@ -0,0 +1,20 @@ +# Authentication + +## Introduction + +Livebook's authentication covers all pages for creating, writing, and managing notebooks. + +Livebook's default authentication method is token authentication. A token is automatically generated at startup and printed to the logs. + +You may optionally enable password-based authentication by setting the environment variable `LIVEBOOK_PASSWORD` on startup or deployment. It must be at least 12 characters. + +To disable authentication altogether, you may set the environment variable `LIVEBOOK_TOKEN_ENABLED` to `false`. + +## Securing deployed notebooks + +When you deploy a notebook as an application, the deployed application is not covered by Livebook's token/password authentication. In such cases, you have two options: + + * You can set a password when deploying your notebook + + * You can enable proxy authentication when deploying inside a cloud infrastructure. + See the "Deployment" section on the sidebar for more information diff --git a/docs/authentication/cloudflare.md b/docs/authentication/cloudflare.md deleted file mode 100644 index 35eee31b5..000000000 --- a/docs/authentication/cloudflare.md +++ /dev/null @@ -1,10 +0,0 @@ -# Authentication with Cloudflare - -To integrate your Cloudflare Zero Trust authentication with Livebook, set the -`LIVEBOOK_IDENTITY_PROVIDER` environment variable to `cloudflare:`. - -For more details about how to find your `team-name`, see: -https://developers.cloudflare.com/cloudflare-one/glossary/#team-name. - -For more information about Cloudflare Zero Trust, see: -https://developers.cloudflare.com/cloudflare-one/. diff --git a/docs/authentication/google_iap.md b/docs/authentication/google_iap.md deleted file mode 100644 index 4970a7ddb..000000000 --- a/docs/authentication/google_iap.md +++ /dev/null @@ -1,11 +0,0 @@ -# Authentication with Google IAP - -To integrate your Google Identity-Aware Proxy (IAP) authentication with Livebook, -set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `google_iap:`. - -For more information about Google IAP, see https://cloud.google.com/iap/docs/concepts-overview. - -Only access with Google accounts is supported. See https://cloud.google.com/iap/docs/authenticate-users-google-accounts. - -For more details about how to find your JWT audience, see: https://cloud.google.com/iap/docs/signed-headers-howto -and look for "Signed Header JWT Audience." \ No newline at end of file diff --git a/docs/authentication/token_authentication.md b/docs/authentication/token_authentication.md deleted file mode 100644 index 271fb05aa..000000000 --- a/docs/authentication/token_authentication.md +++ /dev/null @@ -1,8 +0,0 @@ -# Token authentication - -Livebook's default authentication method is token authentication. - -A token is automatically generated at startup and printed to the logs. The token can be customized -by setting the environment variable `LIVEBOOK_PASSWORD`, and must be at least 12 characters. - -To disable token authentication, set the environment variable `LIVEBOOK_TOKEN_ENABLED` to `false`. \ No newline at end of file diff --git a/docs/deployment/cloudflare.md b/docs/deployment/cloudflare.md new file mode 100644 index 000000000..afa22489d --- /dev/null +++ b/docs/deployment/cloudflare.md @@ -0,0 +1,20 @@ +# Authentication with Cloudflare + +Setting up Cloudflare authentication will protect all routes of your notebook. It is particularly useful for adding authentication to deployed notebooks. Cloudflare authentication is provided in addition to [Livebook's authentication](../authentication.md) for authoring notebooks. + +Once Cloudflare is enabled, 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. + +## How to + +To integrate your Cloudflare Zero Trust authentication with Livebook, set the +`LIVEBOOK_IDENTITY_PROVIDER` environment variable to `cloudflare:`. + +For more details about how to find your `team-name`, see: +https://developers.cloudflare.com/cloudflare-one/glossary/#team-name. + +For more information about Cloudflare Zero Trust, see: +https://developers.cloudflare.com/cloudflare-one/. + +## Livebook Teams + +[Livebook Teams](https://livebook.dev/teams/) users have access to airgapped notebook deployment via Docker, 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. diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md new file mode 100644 index 000000000..8419e9821 --- /dev/null +++ b/docs/deployment/docker.md @@ -0,0 +1,27 @@ +# Docker + +## Dockerfile + +You can deploy Livebook inside your infrastructure using Docker. The Dockerfile below provides a great starting point: + +```dockerfile +FROM ghcr.io/livebook-dev/livebook:edge + +# Configure your port accordingly +ENV LIVEBOOK_PORT 7860 +EXPOSE 7860 + +# If you have a persistent volume, configure it here +ENV LIVEBOOK_DATA_PATH "/data" +USER root +RUN mkdir -p /data +RUN chmod 777 /data +``` + +You can consult our [README](../../README.md#environment-variables) for a complete list of environment variables and configuration. + +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. + +## Livebook Teams + +[Livebook Teams](https://livebook.dev/teams/) users have access to airgapped notebook deployment via Docker, 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. diff --git a/docs/deployment/google_iap.md b/docs/deployment/google_iap.md new file mode 100644 index 000000000..532db2e4e --- /dev/null +++ b/docs/deployment/google_iap.md @@ -0,0 +1,20 @@ +# Authentication with Google IAP + +Setting up Google IAP authentication will protect all routes of your notebook. It is particularly useful for adding authentication to deployed notebooks. Google IAP authentication is provided in addition to [Livebook's authentication](../authentication.md) for authoring notebooks. + +Once Google IAP is enabled, 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. + +## How to + +To integrate your Google Identity-Aware Proxy (IAP) authentication with Livebook, +set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `google_iap:`. + +For more information about Google IAP, see https://cloud.google.com/iap/docs/concepts-overview. + +Only access with Google accounts is supported. See https://cloud.google.com/iap/docs/authenticate-users-google-accounts. + +For more details about how to find your JWT audience, see https://cloud.google.com/iap/docs/signed-headers-howto and look for "Signed Header JWT Audience." + +## Livebook Teams + +[Livebook Teams](https://livebook.dev/teams/) users have access to airgapped notebook deployment via Docker, 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. diff --git a/docs/authentication/tailscale.md b/docs/deployment/tailscale.md similarity index 56% rename from docs/authentication/tailscale.md rename to docs/deployment/tailscale.md index 0be2f4284..24f47ead5 100644 --- a/docs/authentication/tailscale.md +++ b/docs/deployment/tailscale.md @@ -1,7 +1,13 @@ # Authentication with Tailscale +Setting up Tailscale authentication will protect all routes of your notebook. It is particularly useful for adding authentication to deployed notebooks. Tailscale authentication is provided in addition to [Livebook's authentication](../authentication.md) for authoring notebooks. + +Once Tailscale is enabled, 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. + +## How to + To integrate Tailscale authentication with Livebook, -set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `tailscale:tailscale-socket-path`. +set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `tailscale:tailscale-socket-path`, make sure the `tailscale` CLI is installed and available on your machine (or your Docker image). If you want to access Livebook on the same machine as you are hosting it, you must also set the `LIVEBOOK_IP` variable to your Tailscale IP. @@ -17,7 +23,7 @@ livebook server See https://tailscale.com/blog/tailscale-auth-nginx/ for more information on how Tailscale authentication works. -## macOS +### macOS On macOS, when Tailscale is installed via the Mac App Store, no unix socket is exposed. Instead, a TCP port is made available and protected via a password, which needs to be located. @@ -32,4 +38,8 @@ pass=$(echo "$addr_info" | cut -d '-' -f 2) LIVEBOOK_IP=$(exec $(ps -xo comm | grep MacOS/Tailscale$) ip | head -1 | tr -d '\n') \ LIVEBOOK_IDENTITY_PROVIDER=tailscale:http://:$pass@127.0.0.1:$port \ livebook server -``` \ No newline at end of file +``` + +## Livebook Teams + +[Livebook Teams](https://livebook.dev/teams/) users have access to airgapped notebook deployment via Docker, 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. diff --git a/lib/livebook/config.ex b/lib/livebook/config.ex index 532cfd241..6eb461546 100644 --- a/lib/livebook/config.ex +++ b/lib/livebook/config.ex @@ -11,34 +11,28 @@ defmodule Livebook.Config do name: "Session", value: "Cookie value", module: LivebookWeb.SessionIdentity, - read_only: true, - link: "https://livebook.dev/", - commands: [] + read_only: true }, %{ type: :cloudflare, name: "Cloudflare", value: "Team name (domain)", module: Livebook.ZTA.Cloudflare, - read_only: false, - link: "https://developers.cloudflare.com/cloudflare-one/", - commands: [] + read_only: false }, %{ type: :google_iap, name: "Google IAP", value: "Audience (aud)", module: Livebook.ZTA.GoogleIAP, - read_only: false, - link: "https://cloud.google.com/iap/docs/concepts-overview" + read_only: false }, %{ type: :tailscale, name: "Tailscale", value: "Tailscale CLI socket path", module: Livebook.ZTA.Tailscale, - read_only: false, - link: "https://hexdocs.pm/livebook/Livebook.ZTA.Tailscale.html" + read_only: false } ] diff --git a/lib/livebook_web/live/hub/edit/team_component.ex b/lib/livebook_web/live/hub/edit/team_component.ex index 3e7b4fe7a..bd0f613a2 100644 --- a/lib/livebook_web/live/hub/edit/team_component.ex +++ b/lib/livebook_web/live/hub/edit/team_component.ex @@ -194,9 +194,12 @@ defmodule LivebookWeb.Hub.Edit.TeamComponent do
- See - - <%= @zta_metadata.name %> docs + See the + + Authentication with <%= @zta_metadata.name %> docs for more information. diff --git a/mix.exs b/mix.exs index 13b0f83e3..46c9d8222 100644 --- a/mix.exs +++ b/mix.exs @@ -188,22 +188,24 @@ defmodule Livebook.MixProject do defp docs() do [ logo: "static/images/logo.png", - main: "token_authentication", + main: "readme", api_reference: false, extra_section: "Docs", extras: extras(), groups_for_extras: [ - Authentication: Path.wildcard("docs/authentication/*") + Deployment: Path.wildcard("docs/deployment/*") ] ] end defp extras() do [ - "docs/authentication/token_authentication.md", - "docs/authentication/google_iap.md", - "docs/authentication/cloudflare.md", - "docs/authentication/tailscale.md" + "README.md", + "docs/authentication.md", + "docs/deployment/docker.md", + "docs/deployment/cloudflare.md", + "docs/deployment/google_iap.md", + "docs/deployment/tailscale.md" ] end end