Improve docs for clustering, set default (#2293)

Co-authored-by: Jonatan Kłosko <[email protected]>

README.md

@@ -96,6 +96,9 @@ services:
       - LIVEBOOK_IFRAME_PORT=8091
 ```
 
+To run multiple instances of Livebook behind a load balancer,
+see the ["Clustering"](#clustering) section.
+
 ### Embedded devices
 
 If you want to run Livebook on embedded devices, such as Raspberry Pi, BeagleBone, etc.,
@@ -213,9 +216,7 @@ The following environment variables can be used to configure Livebook on boot:
     accesses files from external sources.
 
   * LIVEBOOK_CLUSTER - configures clustering strategy when running multiple
-    instances of Livebook. Currently the only supported value is `dns:QUERY`,
-    in which case nodes ask DNS for A/AAAA records using the given query and
-    try to connect to peer nodes on the discovered IPs.
+    instances of Livebook. See the ["Clustering"](#clustering) section below.
 
   * LIVEBOOK_COOKIE - sets the cookie for running Livebook in a cluster.
     Defaults to a random string that is generated on boot.
@@ -274,7 +275,7 @@ The following environment variables can be used to configure Livebook on boot:
 
   * LIVEBOOK_SECRET_KEY_BASE - sets a secret key that is used to sign and encrypt
     the session and other payloads used by Livebook. Must be at least 64 characters
-    long and it can be generated by commands such as: 'openssl rand -base64 48'.
+    long and it can be generated by commands such as: `openssl rand -base64 48`.
     Defaults to a random secret on every boot.
 
   * LIVEBOOK_SHUTDOWN_ENABLED - controls if a shutdown button should be shown
@@ -306,6 +307,11 @@ The following environment variables can be used to configure Livebook on boot:
 
 <!-- Environment variables -->
 
+If running Livebook via the command line, run `livebook server --help` to see
+all CLI-specific options.
+
+### Livebook Desktop
+
 When running Livebook Desktop, Livebook will invoke on boot a file named
 `~/.livebookdesktop.sh` on macOS or `%USERPROFILE%\.livebookdesktop.bat`
 on Windows. This file can set environment variables used by Livebook,
@@ -322,8 +328,26 @@ such as:
 Be careful when modifying boot files, Livebook may be unable to start if
 configured incorrectly.
 
-If running Livebook via the command line, run `livebook server --help` to see
-all CLI-specific options.
+### Clustering
+
+Clustering is enabled via the `LIVEBOOK_CLUSTER` environment variable.
+Currently the only supported value is `dns:QUERY`, in which case nodes
+ask DNS for A/AAAA records using the given query and try to connect to
+peer nodes on the discovered IPs.
+
+When clustering is enabled, 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 `RELEASE_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"`
+
+`LIVEBOOK_DISTRIBUTION` is automatically set to `name` if clustering is
+enabled.
 
 ## Development
 
@@ -344,7 +368,7 @@ mix test
 Once you submit a pull request, [Uffizzi](https://www.uffizzi.com) will setup
 a preview environment where anyone can try out your changes and give feedback.
 
-### Livebook Desktop
+### Desktop app builds
 
 For macOS, run:
 

lib/livebook/hubs/dockerfile.ex

@@ -123,7 +123,6 @@ defmodule Livebook.Hubs.Dockerfile do
         RUN printf '\
         #!/bin/bash\n\
         export ERL_AFLAGS="-proto_dist inet6_tcp"\n\
-        export LIVEBOOK_DISTRIBUTION="name"\n\
         export LIVEBOOK_NODE="${FLY_APP_NAME}-${FLY_IMAGE_REF##*-}@${FLY_PRIVATE_IP}"\n\
         export LIVEBOOK_CLUSTER="dns:${FLY_APP_NAME}.internal"\n\
         /app/bin/livebook start\n\

rel/server/env.bat.eex

@@ -1,7 +1,8 @@
+set RELEASE_MODE=interactive
 if defined LIVEBOOK_NODE set RELEASE_NODE="!LIVEBOOK_NODE!"
 if not defined RELEASE_NODE set RELEASE_NODE=livebook_server
 if defined LIVEBOOK_DISTRIBUTION set RELEASE_DISTRIBUTION="!LIVEBOOK_DISTRIBUTION!"
-set RELEASE_MODE=interactive
+if not defined RELEASE_DISTRIBUTION (if defined LIVEBOOK_CLUSTER set RELEASE_DISTRIBUTION="name")
 
 set cookie_path="!RELEASE_ROOT!\releases\COOKIE"
 if not exist %cookie_path% (

rel/server/env.sh.eex

@@ -1,6 +1,7 @@
-export RELEASE_NODE=${LIVEBOOK_NODE:-${RELEASE_NODE:-livebook_server}}
-export RELEASE_DISTRIBUTION=${LIVEBOOK_DISTRIBUTION:-${RELEASE_DISTRIBUTION:-sname}}
 export RELEASE_MODE=interactive
+export RELEASE_NODE=${LIVEBOOK_NODE:-${RELEASE_NODE:-livebook_server}}
+if [[ -z "${LIVEBOOK_CLUSTER}" ]]; then DISTRIBUTION_DEFAULT="sname"; else DISTRIBUTION_DEFAULT="name"; fi
+export RELEASE_DISTRIBUTION=${LIVEBOOK_DISTRIBUTION:-${RELEASE_DISTRIBUTION:-${DISTRIBUTION_DEFAULT}}}
 
 cookie_path="${RELEASE_ROOT}/releases/COOKIE"
 if [ ! -f $cookie_path ] && [ -z "$RELEASE_COOKIE" ]; then