Deployment guide

Livebook

Overview

Livebook is the open source interactive and collaborative notebook for Elixir. You combine code cells (Elixir and Erlang), Markdown prose, live inputs, data tables and charts in one reproducible .livemd document. The BEAM runs each cell as real code, so notebooks are always live rather than static. Typical uses are data exploration, prototyping, teaching, building internal tools and producing reproducible reports.

Livebook executes arbitrary code, so an open Livebook is effectively remote code execution. This image is therefore secure by default. The SecureAnyCloud image installs Livebook 0.19.8 on Erlang/OTP 28 and Elixir 1.20. It runs the server bound to loopback behind an nginx reverse proxy that terminates HTTPS with a per-VM self-signed certificate. It persists your notebooks on a dedicated Azure data disk, and it generates a unique access password on the first boot of every VM, with no default login.

What you get:

Livebook 0.19.8 (Apache 2.0) as a self-contained escript at /opt/livebook/livebook.
Erlang/OTP 28.5.0.3 and Elixir 1.20.2 on the system PATH, which is the notebook runtime the BEAM spawns per session.
nginx on :443 terminating HTTPS in front of the loopback Livebook server, with WebSocket proxying for Livebook's live collaborative sessions.
A per-VM access password and per-VM TLS certificate generated on first boot, never baked into the image.
A dedicated Azure data disk at /var/lib/livebook holding your notebooks, separate from the OS disk and re-provisioned with every VM.
A sample welcome.livemd notebook on the data disk.
livebook.service and nginx.service as systemd units, enabled and active.
24/7 SecureAnyCloud support.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet and subnet in the target region.
Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point. Scale up for heavier notebooks.
NSG inbound rules: allow 22/tcp from your management network and 443/tcp for the web UI. You can also allow 80/tcp, which only issues a redirect to HTTPS.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Livebook by SecureAnyCloud, and select Create.

On Basics, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTPS (443).

Review the dedicated data disk on the Disks tab. Then select Review + create, and then Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:livebook-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name livebook \
  --image sac1647283583153:livebook-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard
az vm open-port --resource-group <your-rg> --name livebook --port 443 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active livebook.service nginx.service

Both report active. The Livebook server binds to loopback 127.0.0.1:8080. nginx is the only network-facing listener, terminating HTTPS on :443:

Step 5 - Retrieve your access password

A unique access password is generated on the first boot of your VM and written to a root-only file:

sudo grep '^LIVEBOOK_PASSWORD=' /root/livebook-credentials.txt

The file also records the sign-in URL and the Erlang distribution cookie. The secret values are shown redacted here. Store the real password somewhere safe.

Step 6 - Check the health endpoint

Livebook serves an unauthenticated health endpoint that nginx exposes over HTTPS for load balancers and probes:

curl -sk -o /dev/null -w 'HTTP %{http_code}\n' https://localhost/public/health

It returns HTTP 200. An unauthenticated request to the application root is redirected to the sign-in page, which confirms that the notebook is protected out of the box.

Step 7 - Sign in to the web UI

Browse to https://<vm-public-ip>/. The certificate is a per-VM self-signed certificate, so your browser warns once. Proceed to continue, or install a real certificate as described under Enabling a trusted certificate.

Livebook asks for the access password from Step 5. After you sign in, Livebook opens its home page with the sidebar, your starred notebooks and example notebooks to get started.

Step 8 - Run an Elixir notebook

Click New notebook (top right) to open the notebook editor. Each cell can be Elixir code or Markdown.

Type an expression into the code cell and press the Evaluate button (or Ctrl/Cmd + Enter). Livebook starts a fresh Elixir runtime on the BEAM and renders the result underneath the cell.

The bundled welcome.livemd notebook on the data disk demonstrates code cells, Markdown and a chart. Click Open on the home page and browse to /var/lib/livebook/notebooks/welcome.livemd.

Step 9 - Explore the built-in examples

The Learn section in the sidebar ships a set of example notebooks covering the Elixir ecosystem. They range from a guided tour to plotting with VegaLite and building apps with Kino. Open any of them to start experimenting.

Step 10 - Verify the security posture

Confirm the shipped versions and that the notebook requires authentication out of the box:

cat /opt/livebook/VERSION

An unauthenticated request to the root is redirected to the sign-in page. The notebook grants access only once the per-VM password is supplied.

You can prove the full password round trip from the VM at any time:

sudo /opt/livebook/livebook-selftest.sh

It confirms three things: the health endpoint returns 200, an unauthenticated request is redirected, and the per-VM password authenticates over TLS.

Step 11 - Confirm the notebooks live on the dedicated disk

Your notebooks are stored on the dedicated Azure data disk, so they survive OS changes and can be resized independently:

findmnt /var/lib/livebook

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM. Add your own .livemd notebooks under /var/lib/livebook/notebooks.

Rotating the access password

The access password lives in /opt/livebook/livebook.env. To change it, edit that file and restart the service:

sudo nano /opt/livebook/livebook.env
# edit LIVEBOOK_PASSWORD (minimum 12 characters)
sudo systemctl restart livebook

Enabling a trusted certificate

nginx terminates TLS on port 443 with a per-VM self-signed certificate at /etc/nginx/tls/livebook.crt.

For production, add a DNS name for the VM and replace the certificate with a CA-signed one. Alternatively, put the companion SecureAnyCloud nginx-ssl-certbot image in front as a TLS reverse proxy.

Keep Livebook bound to loopback, so the only public surface is the authenticated, TLS-terminating proxy. It already forwards the WebSocket that Livebook's live sessions need.

Maintenance

Your notebooks: add .livemd files to /var/lib/livebook/notebooks/ (owned by livebook:livebook). They appear on the Livebook home page.
Backups: snapshot the /var/lib/livebook data disk.
Upgrades: rebuild the escript with a newer release using the Elixir and Erlang on the PATH, then restart livebook.
Security patches: unattended-upgrades remains enabled, so the OS continues to receive security updates automatically.

Support

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Deploy on Azure

Launch Livebook on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

Livebook is the open source interactive and collaborative notebook for Elixir. A notebook mixes Elixir code cells, Markdown prose, live inputs, data tables and charts in one document. That document is a plain-text .livemd file, so you can commit a notebook to version control next to the code it describes, and someone else can re-run it unchanged.

Livebook evaluates arbitrary Elixir, so an unprotected instance would be remote code execution. This image never ships an open or default credential. On the first boot of every deployed instance, a one-shot service generates a unique access password and a unique Erlang distribution cookie. Two instances launched from the same Amazon Machine Image never share a password.

What you get:

A complete BEAM toolchain. Erlang/OTP 28.5.0.3 is compiled from the official pinned source tarball with its checksum verified during the build and installed into /usr/local. Elixir 1.20.2 is the official pinned precompiled release, unpacked to /opt/elixir with elixir, elixirc, iex and mix symlinked onto the default PATH.
Both toolchains stay on the instance at run time, because Livebook's default notebook runtime spawns a fresh Elixir node for each notebook session.
Livebook as a self-contained escript at /opt/livebook/livebook, run by livebook.service as a dedicated unprivileged livebook system user.
A notebook server that binds the loopback interface only, on 127.0.0.1:8080, with its iframe sandbox on 127.0.0.1:8081. It is never directly reachable from the network.
nginx terminating TLS on port 443 and reverse proxying to the notebook server with WebSocket upgrade headers. This is what makes Livebook's LiveView interface and collaborative editing work through the proxy.
Port 80 returning a redirect to HTTPS and serving an unauthenticated /healthz endpoint for load balancer probes.
A unique 28-character access password and Erlang distribution cookie written on first boot to /opt/livebook/livebook.env with mode 0640.
A self-signed TLS certificate regenerated on first boot, carrying that instance's own address in its subject alternative names.
The password recorded in /root/livebook-credentials.txt with mode 0600, so only the root user can read it.
Notebooks and Livebook's internal state at /var/lib/livebook, on a dedicated, independently resizable EBS data volume referenced in /etc/fstab by filesystem UUID.

Prerequisites

Before you deploy this image you need:

An Amazon Web Services account where you can launch EC2 instances.
IAM permissions to launch instances, create security groups and subscribe to AWS Marketplace products.
An EC2 key pair in the target Region for SSH access to the instance.
A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 443 for the Livebook web interface.
The AWS CLI (version 2) installed locally, if you plan to deploy from the command line.

Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Livebook. Select the SecureAnyCloud listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet. Create or select a security group that opens port 22 from your management network and port 443 for the Livebook web interface. Leave the root volume at the default size or larger.

Select Launch instance. First-boot initialization takes a short time after the instance state becomes Running and the status checks pass. During this time the image generates the access password, regenerates the TLS certificate and starts the notebook server.

Launch the Instance from the AWS CLI

The following command launches an instance from the SecureAnyCloud Livebook Marketplace AMI into an existing subnet and security group. Replace these values first:

<ami-id>: the AMI ID shown on the Marketplace listing.
<key-name>: your EC2 key pair name.
<subnet-id>: your subnet ID.
<security-group-id>: a security group that opens ports 22 and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=livebook}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Connect to Your Instance

Connect over SSH using your key pair. On Ubuntu 24.04, the SSH login user is ubuntu.

ssh -i <your-key.pem> ubuntu@<public-ip>

Retrieve the Access Password

The access password is generated on the first boot of this instance and written to a root-only file. Read it over SSH.

sudo cat /root/livebook-credentials.txt

The file records the password, the URL to open and the Erlang distribution cookie:

# Livebook - this instance. Generated on first boot by livebook-firstboot.service.
#
# Livebook executes arbitrary Elixir, so it is PASSWORD PROTECTED out of the box.
# Open the Web UI below and sign in with LIVEBOOK_PASSWORD.
# LIVEBOOK_PASSWORD=<generated on your instance> LIVEBOOK_URL=https://<your-instance-address>/ LIVEBOOK_COOKIE=<generated on your instance>

Confirm the file is readable only by root:

sudo stat -c '%a %U:%G' /root/livebook-credentials.txt

This reports 600 root:root.

Confirm the Services Are Running

Two units serve the product: livebook.service and nginx.service.

systemctl is-active livebook nginx

Both report active.

Confirm the installed versions:

cat /opt/livebook/VERSION

livebook_version=0.19.8 erlang_otp=28.5.0.3 elixir=1.20.2

The Elixir and Erlang runtimes are on the default PATH:

elixir --version | grep -E '^Elixir ' erl -noshell -eval 'io:format("OTP ~s~n",[erlang:system_info(otp_release)]), halt().'

These report Elixir 1.20.2 (compiled with Erlang/OTP 28) and OTP 28.

Confirm that the notebook server is bound to the loopback interface only, and that nginx is the sole network-facing listener:

ss -tln | grep -E ':(80|443|8080|8081) ' | awk '{print $1,$4}'

Ports 8080 and 8081 appear only as 127.0.0.1, while 80 and 443 are published.

Check the health endpoints. The /healthz endpoint on port 80 is unauthenticated and is intended for load balancer probes. The /public/health endpoint is Livebook's own health endpoint, served over HTTPS.

curl -s -o /dev/null -w 'http :80/healthz: %{http_code}\n' http://127.0.0.1/healthz
curl -s -o /dev/null -w 'http :80/: %{http_code}\n' http://127.0.0.1/
curl -ks -o /dev/null -w 'https :443/public/health: %{http_code}\n' https://127.0.0.1/public/health
curl -ks -o /dev/null -w 'https :443/ unauthenticated: %{http_code}\n' https://127.0.0.1/

These report 200, 301, 200 and 302 respectively. The 301 is the redirect from HTTP to HTTPS. The 302 on the last line is the authentication wall: an unauthenticated request for a notebook is redirected to the sign-in page, never served.

You can prove the whole authentication path end to end at any time. The image ships a self-test that reads the per-instance password and drives the sign-in form. It confirms that an authenticated request succeeds while an unauthenticated one does not.

sudo /opt/livebook/livebook-selftest.sh

round-trip OK: health=200, unauth GET /=302 (protected), authenticated GET /=200 - per-instance password proven over TLS

Sign In to Livebook

Open https://<public-ip>/ in your browser. The certificate is self-signed and generated for this instance, so your browser warns on the first visit. Accept it to continue, or follow Step 10 to install a certificate from a public authority.

Livebook presents its authentication wall. Enter the LIVEBOOK_PASSWORD from Step 4.

After you sign in, you land on the Livebook home screen. It lists your notebooks, the learning notebooks that ship with Livebook, and any running sessions.

Open a Notebook and Evaluate a Cell

A sample notebook ships on the data volume at /var/lib/livebook/notebooks/welcome.livemd. Confirm it is present:

ls /var/lib/livebook/notebooks/

From the Livebook home screen choose Open, then browse to /var/lib/livebook/notebooks and select welcome.livemd. The notebook opens with its Markdown prose rendered and its Elixir code cells ready to run.

Select Evaluate on the first code cell, or press Ctrl (or Cmd) and Enter with the cursor in the cell. Livebook starts a notebook runtime, evaluates the cell on the BEAM, and renders the result inline beneath it.

Choose New notebook on the home screen to start your own. Save it into /var/lib/livebook/notebooks so that it lives on the dedicated data volume.

The Data Volume

Notebooks and Livebook's internal state live on a dedicated EBS volume mounted at /var/lib/livebook, separate from the operating system disk so it can be resized, snapshotted and restored independently.

findmnt -no SOURCE,TARGET,FSTYPE,SIZE /var/lib/livebook df -h /var/lib/livebook | tail -1

The mount is referenced in /etc/fstab by filesystem UUID rather than by device name, because NVMe device names are not stable across reboots.

grep livebook /etc/fstab

Two environment settings in livebook.service point Livebook at this volume: LIVEBOOK_HOME is /var/lib/livebook/notebooks, which is the directory the file browser opens in, and LIVEBOOK_DATA_PATH is /var/lib/livebook/data, where Livebook keeps its own state.

To grow the volume, expand it in the EC2 console or with aws ec2 modify-volume, then extend the filesystem in place with sudo resize2fs /dev/<device>.

Rotate the Access Password

The password is read from /opt/livebook/livebook.env at service start. To rotate it, set a new value in that file, mirror it into your record at /root/livebook-credentials.txt, and restart the service. Existing browser sessions are invalidated.

The block below is shown for reference only, because it changes the credential on the instance you run it on. Substitute your own new password for <new-password>:

sudo sed -i 's/^LIVEBOOK_PASSWORD=.*/LIVEBOOK_PASSWORD=<new-password>/' /opt/livebook/livebook.env
sudo sed -i 's/^LIVEBOOK_PASSWORD=.*/LIVEBOOK_PASSWORD=<new-password>/' /root/livebook-credentials.txt
sudo systemctl restart livebook

Both files must carry the same value, because the self test reads the credentials file while the service reads the environment file. Confirm the new password authenticates:

sudo /opt/livebook/livebook-selftest.sh

The LIVEBOOK_COOKIE value in the same file is the Erlang distribution cookie. Change it only if you intend to cluster this node with other BEAM nodes, and keep it secret.

Replace the Self-Signed Certificate

The certificate generated at first boot is self-signed, which is why browsers warn on the first visit. For anything beyond evaluation, point a DNS name at the instance and install a certificate from a public authority.

Install certbot and request a certificate, replacing <your-domain> with your DNS name and <your-email> with your contact address:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain> -m <your-email> --agree-tos --no-eff-email

Certbot edits the nginx server block in place and installs a renewal timer. The reverse proxy configuration, including the WebSocket upgrade headers Livebook needs, is at /etc/nginx/sites-available/sac-livebook. If you edit it by hand, test before reloading:

sudo nginx -t

Alternatively, terminate TLS on an Application Load Balancer in front of the instance and leave the instance certificate in place for the internal hop.

Backup and Maintenance

Notebooks are plain-text .livemd files on a dedicated volume, so backup is straightforward. Take EBS snapshots of the /var/lib/livebook volume on a schedule, or sync the notebook directory to Amazon S3:

sudo tar -czf /tmp/livebook-notebooks.tar.gz -C /var/lib/livebook notebooks

Copy the resulting archive off the instance, then remove it:

sudo rm -f /tmp/livebook-notebooks.tar.gz

The image ships with unattended security updates enabled, exactly as stock Ubuntu.

When troubleshooting, confirm that the notebook server logged a successful start:

sudo journalctl -u livebook --no-pager | grep -c 'Application running at'

A count of one or more means the server bound its port and came up. To read the full service log, including any evaluation errors reported by a notebook runtime, run:

sudo journalctl -u livebook --no-pager -n 200

To restart the product cleanly:

sudo systemctl restart livebook nginx systemctl is-active livebook nginx

Support

SecureAnyCloud provides 24/7 technical support for this image by email and live chat at sales@secureanycloud.com. Include your instance ID and AWS Region to speed up troubleshooting.

Livebook, Elixir and Erlang are trademarks of their respective owners. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Deploy on AWS

Launch Livebook on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS