Move zta authentication docs from module docs to custom pages docs (#2215)

docs/authentication/cloudflare.md

@@ -0,0 +1,10 @@
+# Authentication with Cloudflare
+
+To integrate your Cloudflare Zero Trust authentication with Livebook, set the
+`LIVEBOOK_IDENTITY_PROVIDER` environment variable to `cloudflare:<your-team-name>`.
+
+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/.

docs/authentication/google_iap.md

@@ -0,0 +1,11 @@
+# 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:<your-jwt-audience>`.
+
+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."

docs/authentication/tailscale.md

@@ -0,0 +1,35 @@
+# Authentication with Tailscale
+
+To integrate Tailscale authentication with Livebook,
+set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `tailscale:tailscale-socket-path`.
+
+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.
+
+To do both of these things, run:
+
+```bash
+LIVEBOOK_IP=$(tailscale ip -1 | tr -d '\n') \
+LIVEBOOK_IDENTITY_PROVIDER=tailscale:/var/run/tailscale/tailscaled.sock \
+livebook server
+```
+
+See https://tailscale.com/blog/tailscale-auth-nginx/ for more information
+on how Tailscale authentication works.
+
+## 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.
+Tailscale itself uses lsof for this. This method is replicated in the bash script below,
+which will start Livebook with your Tailscale IP and correct port and password.
+
+```bash
+#!/bin/bash
+addr_info=$(lsof -n -a -c IPNExtension -F | sed -n 's/.*sameuserproof-\([[:digit:]]*-.*\).*/\1/p')
+port=$(echo "$addr_info" | cut -d '-' -f 1)
+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
+```

docs/authentication/token_authentication.md

@@ -0,0 +1,8 @@
+# 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`.

lib/livebook/zta/cloudflare.ex

@@ -1,15 +1,4 @@
 defmodule Livebook.ZTA.Cloudflare do
-  @moduledoc """
-  To integrate your Cloudflare Zero Trust authentication with Livebook,
-  set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `cloudflare:<your-team-name>`
-
-  For more information about Cloudflare Zero Trust,
-  see: https://developers.cloudflare.com/cloudflare-one/
-
-  For more details about how to find your team-name,
-  see: https://developers.cloudflare.com/cloudflare-one/glossary/#team-name
-  """
-
   use GenServer
   require Logger
   import Plug.Conn

lib/livebook/zta/google_iap.ex

@@ -1,19 +1,4 @@
 defmodule Livebook.ZTA.GoogleIAP do
-  @moduledoc """
-  To integrate your Google Identity-Aware Proxy (IAP) authentication with Livebook,
-  set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `google_iap:<your-jwt-audience>`
-
-  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"
-  """
-
   use GenServer
   require Logger
   import Plug.Conn

lib/livebook/zta/tailscale.ex

@@ -1,36 +1,4 @@
 defmodule Livebook.ZTA.Tailscale do
-  @moduledoc """
-  To integrate Tailscale authentication with Livebook,
-  set the `LIVEBOOK_IDENTITY_PROVIDER` environment variable to `tailscale:tailscale-socket-path`.
-
-  If you want to access the Livebook on the same machine as you are hosting it on,
-  you will also need to set the LIVEBOOK_IP variable to your Tailscale IP.
-
-  To do both of these things, run
-
-  ```bash
-  LIVEBOOK_IP=$(tailscale ip -1 | tr -d '\n') LIVEBOOK_IDENTITY_PROVIDER=tailscale:/var/run/tailscale/tailscaled.sock livebook server
-  ```
-
-  See https://tailscale.com/blog/tailscale-auth-nginx/ for more information
-  on how Tailscale authorization works.
-
-  ## MacOS
-
-  On MacOS, when Tailscale is installed via the Mac App Store, no unix socket is exposed.
-  Instead, a TCP port is made available, protected via a password, which needs to be located.
-  Tailscale itself uses lsof for this. This method is replicated in the bash script below,
-  which will start Livebook with your Tailscale IP and correct port and password.
-
-  ```bash
-  #!/bin/bash
-  addr_info=$(lsof -n -a -c IPNExtension -F | sed -n 's/.*sameuserproof-\([[:digit:]]*-.*\).*/\1/p')
-  port=$(echo "$addr_info" | cut -d '-' -f 1)
-  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
-  ```
-  """
-
   use GenServer
   require Logger
 

mix.exs

@@ -20,7 +20,11 @@ defmodule Livebook.MixProject do
       escript: escript(),
       package: package(),
       default_release: :livebook,
-      releases: releases()
+      releases: releases(),
+
+      # Docs
+      homepage_url: "https://livebook.dev",
+      docs: docs()
     ]
   end
 
@@ -112,7 +116,9 @@ defmodule Livebook.MixProject do
       # ZTA deps
       {:jose, "~> 1.11.5"},
       {:req, "~> 0.3.8"},
-      {:bandit, "~> 0.7", only: :test}
+      {:bandit, "~> 0.7", only: :test},
+      # Docs
+      {:ex_doc, "~> 0.30", only: :dev, runtime: false}
     ]
   end
 
@@ -178,4 +184,26 @@ defmodule Livebook.MixProject do
     |> Standalone.copy_hex()
     |> Standalone.copy_rebar3(rebar3_version)
   end
+
+  defp docs() do
+    [
+      logo: "static/images/logo.png",
+      main: "token_authentication",
+      api_reference: false,
+      extra_section: "Docs",
+      extras: extras(),
+      groups_for_extras: [
+        Authentication: Path.wildcard("docs/authentication/*")
+      ]
+    ]
+  end
+
+  defp extras() do
+    [
+      "docs/authentication/token_authentication.md",
+      "docs/authentication/google_iap.md",
+      "docs/authentication/cloudflare.md",
+      "docs/authentication/tailscale.md"
+    ]
+  end
 end

mix.lock

@@ -9,16 +9,21 @@
   "decimal": {:hex, :decimal, "2.1.1", "5611dca5d4b2c3dd497dec8f68751f1f1a54755e8ed2a966c2633cf885973ad6", [:mix], [], "hexpm", "53cfe5f497ed0e7771ae1a475575603d77425099ba5faef9394932b35020ffcc"},
   "earmark_parser": {:hex, :earmark_parser, "1.4.33", "3c3fd9673bb5dcc9edc28dd90f50c87ce506d1f71b70e3de69aa8154bc695d44", [:mix], [], "hexpm", "2d526833729b59b9fdb85785078697c72ac5e5066350663e5be6a1182da61b8f"},
   "ecto": {:hex, :ecto, "3.10.2", "6b887160281a61aa16843e47735b8a266caa437f80588c3ab80a8a960e6abe37", [:mix], [{:decimal, "~> 1.6 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "6a895778f0d7648a4b34b486af59a1c8009041fbdf2b17f1ac215eb829c60235"},
+  "ex_doc": {:hex, :ex_doc, "0.30.6", "5f8b54854b240a2b55c9734c4b1d0dd7bdd41f71a095d42a70445c03cf05a281", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "bd48f2ddacf4e482c727f9293d9498e0881597eae6ddc3d9562bd7923375109f"},
   "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
   "finch": {:hex, :finch, "0.16.0", "40733f02c89f94a112518071c0a91fe86069560f5dbdb39f9150042f44dcfb1a", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: false]}, {:mime, "~> 1.0 or ~> 2.0", [hex: :mime, repo: "hexpm", optional: false]}, {:mint, "~> 1.3", [hex: :mint, repo: "hexpm", optional: false]}, {:nimble_options, "~> 0.4 or ~> 1.0", [hex: :nimble_options, repo: "hexpm", optional: false]}, {:nimble_pool, "~> 0.2.6 or ~> 1.0", [hex: :nimble_pool, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "f660174c4d519e5fec629016054d60edd822cdfe2b7270836739ac2f97735ec5"},
   "floki": {:hex, :floki, "0.34.3", "5e2dcaec5d7c228ce5b1d3501502e308b2d79eb655e4191751a1fe491c37feac", [:mix], [], "hexpm", "9577440eea5b97924b4bf3c7ea55f7b8b6dce589f9b28b096cc294a8dc342341"},
   "hpax": {:hex, :hpax, "0.1.1", "2396c313683ada39e98c20a75a82911592b47e5c24391363343bde74f82396ca", [:mix], [], "hexpm", "0ae7d5a0b04a8a60caf7a39fcf3ec476f35cc2cc16c05abea730d3ce6ac6c826"},
   "jason": {:hex, :jason, "1.4.0", "e855647bc964a44e2f67df589ccf49105ae039d4179db7f6271dfd3843dc27e6", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "79a3791085b2a0f743ca04cec0f7be26443738779d09302e01318f97bdb82121"},
   "jose": {:hex, :jose, "1.11.5", "3bc2d75ffa5e2c941ca93e5696b54978323191988eb8d225c2e663ddfefd515e", [:mix, :rebar3], [], "hexpm", "dcd3b215bafe02ea7c5b23dafd3eb8062a5cd8f2d904fd9caa323d37034ab384"},
+  "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.2", "ad87296a092a46e03b7e9b0be7631ddcf64c790fa68a9ef5323b6cbb36affc72", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f3f5a1ca93ce6e092d92b6d9c049bcda58a3b617a8d888f8e7231c85630e8108"},
   "mime": {:hex, :mime, "2.0.5", "dc34c8efd439abe6ae0343edbb8556f4d63f178594894720607772a041b04b02", [:mix], [], "hexpm", "da0d64a365c45bc9935cc5c8a7fc5e49a0e0f9932a761c55d6c52b142780a05c"},
   "mint": {:hex, :mint, "1.5.1", "8db5239e56738552d85af398798c80648db0e90f343c8469f6c6d8898944fb6f", [:mix], [{:castore, "~> 0.1.0 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:hpax, "~> 0.1.1", [hex: :hpax, repo: "hexpm", optional: false]}], "hexpm", "4a63e1e76a7c3956abd2c72f370a0d0aecddc3976dea5c27eccbecfa5e7d5b1e"},
   "mint_web_socket": {:hex, :mint_web_socket, "1.0.3", "aab42fff792a74649916236d0b01f560a0b3f03ca5dea693c230d1c44736b50e", [:mix], [{:mint, ">= 1.4.1 and < 2.0.0-0", [hex: :mint, repo: "hexpm", optional: false]}], "hexpm", "ca3810ca44cc8532e3dce499cc17f958596695d226bb578b2fbb88c09b5954b0"},
   "nimble_options": {:hex, :nimble_options, "1.0.2", "92098a74df0072ff37d0c12ace58574d26880e522c22801437151a159392270e", [:mix], [], "hexpm", "fd12a8db2021036ce12a309f26f564ec367373265b53e25403f0ee697380f1b8"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.3.1", "2c54013ecf170e249e9291ed0a62e5832f70a476c61da16f6aac6dca0189f2af", [:mix], [], "hexpm", "2682e3c0b2eb58d90c6375fc0cc30bc7be06f365bf72608804fb9cffa5e1b167"},
   "nimble_pool": {:hex, :nimble_pool, "1.0.0", "5eb82705d138f4dd4423f69ceb19ac667b3b492ae570c9f5c900bb3d2f50a847", [:mix], [], "hexpm", "80be3b882d2d351882256087078e1b1952a28bf98d0a287be87e4a24a710b67a"},
   "phoenix": {:hex, :phoenix, "1.7.5", "3234bc87185e6a2103a15a3b1399f19775b093a6923c4064436e49cdab8ce5d2", [:mix], [{:castore, ">= 0.0.0", [hex: :castore, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 2.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:phoenix_template, "~> 1.0", [hex: :phoenix_template, repo: "hexpm", optional: false]}, {:phoenix_view, "~> 2.0", [hex: :phoenix_view, repo: "hexpm", optional: true]}, {:plug, "~> 1.14", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 2.6", [hex: :plug_cowboy, repo: "hexpm", optional: true]}, {:plug_crypto, "~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}, {:websock_adapter, "~> 0.5.1", [hex: :websock_adapter, repo: "hexpm", optional: false]}], "hexpm", "5abad1789f06a3572ee5e5d5151993ed35b9e2711537904cc457a40229587979"},
   "phoenix_ecto": {:hex, :phoenix_ecto, "4.4.2", "b21bd01fdeffcfe2fab49e4942aa938b6d3e89e93a480d4aee58085560a0bc0d", [:mix], [{:ecto, "~> 3.5", [hex: :ecto, repo: "hexpm", optional: false]}, {:phoenix_html, "~> 2.14.2 or ~> 3.0", [hex: :phoenix_html, repo: "hexpm", optional: true]}, {:plug, "~> 1.9", [hex: :plug, repo: "hexpm", optional: false]}], "hexpm", "70242edd4601d50b69273b057ecf7b684644c19ee750989fd555625ae4ce8f5d"},