diff --git a/README.md b/README.md index 38e7450c015..0fcec1ded4d 100644 --- a/README.md +++ b/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: +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: diff --git a/lib/livebook/hubs/dockerfile.ex b/lib/livebook/hubs/dockerfile.ex index d99fdd5dc86..1890edf7fbf 100644 --- a/lib/livebook/hubs/dockerfile.ex +++ b/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\ diff --git a/rel/server/env.bat.eex b/rel/server/env.bat.eex index 22004c25429..ceb35873d56 100644 --- a/rel/server/env.bat.eex +++ b/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% ( diff --git a/rel/server/env.sh.eex b/rel/server/env.sh.eex index b67cd8a6110..c9d51c4a016 100644 --- a/rel/server/env.sh.eex +++ b/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