Deploying Livebook

Introduction

Livebook is a powerful, open-source notebook platform for Elixir that brings interactive computing to the BEAM ecosystem. Similar to Jupyter notebooks for Python, Livebook enables you to write and execute Elixir code in an interactive environment with rich outputs, visualizations, and documentation all in one place. But Livebook goes beyond traditional notebooks with real-time collaboration, automatic dependency management, and the ability to deploy notebooks as applications.

Built by the creators of Elixir at Dashbit, Livebook leverages the BEAM’s unique capabilities for fault tolerance, hot code reloading, and distributed computing. The platform is designed for data exploration, documentation, learning, and building internal tools without the complexity of traditional application development.

Key highlights of Livebook:

• Interactive Elixir: Execute Elixir code with instant feedback and rich outputs
• Real-Time Collaboration: Multiple users can edit and run the same notebook simultaneously
• Smart Cells: Pre-built components for databases, charts, maps, and more
• Automatic Dependencies: Manage Mix dependencies without leaving the notebook
• Visual Exploration: Built-in support for data visualization with VegaLite
• Secret Management: Secure handling of API keys and credentials
• App Deployment: Deploy notebooks as standalone web applications
• CUDA Support: GPU acceleration for machine learning workloads
• Clustering: Connect to remote Elixir nodes for distributed computing
• File Format: Notebooks stored as readable Markdown files
• Open Source: Apache 2.0 licensed with active development

This guide walks through deploying Livebook on Klutch.sh using Docker, configuring persistent storage, and setting up for production use.

Why Deploy Livebook on Klutch.sh

Deploying Livebook on Klutch.sh provides several advantages:

Always Available: Your notebooks and deployed apps remain accessible 24/7 without managing personal infrastructure.

Persistent Storage: Attach persistent volumes for your notebooks and data. Your work survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your notebooks and Livebook apps.

GitHub Integration: Connect your configuration repository directly from GitHub. Push updates to trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your workload. Scale up for data processing or machine learning tasks.

Team Collaboration: Real-time collaboration features enable team members to work together on notebooks.

Environment Variable Security: Store database credentials, API keys, and secrets securely through Klutch.sh’s environment variable system.

Custom Domains: Use your own domain for your Livebook instance and deployed apps.

Prerequisites

Before deploying Livebook on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) Familiarity with Elixir programming
• (Optional) A custom domain for your Livebook instance

Understanding Livebook Architecture

Livebook uses a sophisticated architecture built on the Elixir/BEAM platform:

Phoenix Application: The web interface is built with Phoenix LiveView, providing real-time updates without page refreshes.

Evaluation Runtime: Code execution happens in isolated runtimes, either embedded or in separate Elixir nodes.

File Storage: Notebooks are stored as .livemd files, which are valid Markdown with embedded Elixir code.

Secret Store: Secrets are encrypted and stored separately from notebooks, allowing secure credential management.

Hub System: Optional integration with Livebook Teams for enterprise features like deployment and collaboration.

Preparing Your Repository

To deploy Livebook on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

livebook-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/livebook-dev/livebook:latest

# Set environment variables
ENV LIVEBOOK_PORT=8080
ENV LIVEBOOK_IP=0.0.0.0

# Optional: Set password for access
# If not set, Livebook generates a token shown in logs
ENV LIVEBOOK_PASSWORD=${LIVEBOOK_PASSWORD}

# Configure persistent data path
ENV LIVEBOOK_DATA_PATH=/data

# Create data directory
RUN mkdir -p /data

# Expose the web interface port
EXPOSE 8080

# The base image includes the default entrypoint

Advanced Dockerfile with CUDA Support

For machine learning workloads with GPU support:

FROM ghcr.io/livebook-dev/livebook:latest-cuda

# Set environment variables
ENV LIVEBOOK_PORT=8080
ENV LIVEBOOK_IP=0.0.0.0
ENV LIVEBOOK_PASSWORD=${LIVEBOOK_PASSWORD}
ENV LIVEBOOK_DATA_PATH=/data

# Configure for CUDA
ENV XLA_TARGET=cuda120

# Create data directory
RUN mkdir -p /data

# Expose ports
EXPOSE 8080
EXPOSE 8081

# The base image includes the default entrypoint

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
_build
deps

Environment Variables Reference

Livebook supports extensive configuration through environment variables:

Variable	Required	Default	Description
LIVEBOOK_PORT	No	8080	Port for the web interface
LIVEBOOK_IP	No	127.0.0.1	IP address to bind (use 0.0.0.0 for Docker)
LIVEBOOK_PASSWORD	Recommended	-	Password for access. If not set, a token is generated
LIVEBOOK_DATA_PATH	No	-	Path for persistent data storage
LIVEBOOK_SECRET_KEY_BASE	No	-	Secret key for encryption (auto-generated if not set)
LIVEBOOK_COOKIE	No	-	Erlang cookie for clustering
LIVEBOOK_DEFAULT_RUNTIME	No	standalone	Default runtime: standalone, attached, embedded
LIVEBOOK_HOME	No	-	Default directory for notebooks
LIVEBOOK_IFRAME_PORT	No	8081	Port for iframe sandbox
LIVEBOOK_IFRAME_URL	No	-	URL for iframe sandbox

Deploying Livebook on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Set a Secure Password

Choose a strong password for Livebook access:

openssl rand -base64 24

Save this securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Livebook deployment configuration"
git remote add origin https://github.com/yourusername/livebook-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “livebook” or “elixir-notebooks”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Livebook configuration.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

In the environment variables section, add:

Variable	Value
LIVEBOOK_PORT	8080
LIVEBOOK_IP	0.0.0.0
LIVEBOOK_PASSWORD	Your secure password
LIVEBOOK_DATA_PATH	/data

Attach Persistent Volumes

Add persistent storage for your notebooks and data:

Mount Path	Recommended Size	Purpose
/data	10 GB	Notebooks, secrets, and application data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Livebook container
• Provision an HTTPS certificate

Access Livebook

Once deployment completes, access your Livebook instance at https://your-app-name.klutch.sh and log in with your configured password.

Using Livebook

Creating Notebooks

Start creating interactive notebooks:

1. Click New notebook or press Ctrl/Cmd + N
2. Add sections and cells
3. Write Elixir code and execute with Ctrl/Cmd + Enter

Cell Types

Livebook supports different cell types:

• Code Cells: Execute Elixir code
• Markdown Cells: Documentation and formatting
• Smart Cells: Pre-built interactive components

Smart Cells

Smart Cells provide no-code interfaces for common tasks:

Database Connection:

# Smart Cell generates connection code
connection = Kino.start_child({
  Postgrex,
  hostname: "...", database: "...", username: "...", password: "..."
})

Chart:

• Configure charts visually
• Auto-generates VegaLite code

Map:

• Create interactive maps
• Plot geographic data

Inputs:

• Create forms and inputs
• Collect user data

Managing Dependencies

Add Mix dependencies in code cells:

Mix.install([
  {:jason, "~> 1.4"},
  {:req, "~> 0.4"},
  {:kino, "~> 0.12"},
  {:kino_vega_lite, "~> 0.1"},
  {:explorer, "~> 0.8"},
  {:kino_explorer, "~> 0.1"}
])

Livebook automatically installs dependencies when the cell runs.

Secrets Management

Store sensitive data securely:

1. Click the Secrets button in the sidebar
2. Add a new secret with a name and value
3. Access in code with System.fetch_env!("LB_SECRET_NAME")

Secrets are encrypted and stored separately from notebooks.

Data Visualization

VegaLite Charts

Create interactive visualizations:

alias VegaLite, as: Vl

Vl.new(width: 400, height: 300)
|> Vl.data_from_values(data)
|> Vl.mark(:bar)
|> Vl.encode_field(:x, "category", type: :nominal)
|> Vl.encode_field(:y, "value", type: :quantitative)

Explorer DataFrames

Work with tabular data:

require Explorer.DataFrame, as: DF

df = DF.new(
  name: ["Alice", "Bob", "Charlie"],
  age: [25, 30, 35],
  city: ["NYC", "LA", "Chicago"]
)

DF.filter(df, age > 27)

Kino Widgets

Create interactive outputs:

# Interactive table
Kino.DataTable.new(df)

# Interactive input
name = Kino.Input.text("Enter your name")

# Render Markdown
Kino.Markdown.new("**Hello** _world_!")

# Image display
Kino.Image.new(binary, :png)

Deploying Apps

Livebook Apps

Deploy notebooks as standalone applications:

1. Open the notebook you want to deploy
2. Click the App settings icon
3. Configure app settings:
   • App session mode (single or multi)
   • Show source toggle
   • Output settings
4. Click Deploy

Manual Docker Deployment

Deploy a specific notebook:

1. Open Application pane in sidebar
2. Click Manual Docker deployment
3. Get the Dockerfile and deployment instructions
4. Deploy the generated image

Clustering and Distribution

Connecting to Existing Nodes

Connect Livebook to running Elixir applications:

1. Configure LIVEBOOK_COOKIE to match your app
2. Set runtime to Attached with the node name
3. Access your application’s modules and processes

Running Multiple Instances

For horizontal scaling:

1. Set LIVEBOOK_COOKIE to the same value across instances
2. Configure clustering through environment variables
3. Enable distributed features

Production Best Practices

Security Recommendations

• Strong Password: Use a complex password for LIVEBOOK_PASSWORD
• HTTPS Only: Always access Livebook over HTTPS
• Secret Key Base: Set LIVEBOOK_SECRET_KEY_BASE for consistent encryption
• Access Control: Limit who can access your Livebook instance
• Secret Management: Use Livebook secrets instead of hardcoding credentials

Performance Optimization

• Resource Allocation: Allocate sufficient memory for data processing
• Standalone Runtime: Use standalone runtime for isolation
• Garbage Collection: Large data operations benefit from more memory

Backup Strategy

Protect your notebooks:

1. Notebook Files: Back up /data regularly
2. Git Integration: Store notebooks in Git repositories
3. Export: Export important notebooks as .livemd files

Troubleshooting Common Issues

Cannot Access Livebook

Symptoms: Browser cannot connect to Livebook.

Solutions:

• Check password is entered correctly
• Verify LIVEBOOK_IP is set to 0.0.0.0
• Confirm port 8080 is configured correctly
• Check deployment logs for errors

Dependencies Not Installing

Symptoms: Mix.install fails or hangs.

Solutions:

• Check network connectivity
• Verify Hex and compile tools are available
• Try specific package versions
• Review error messages in cell output

Runtime Errors

Symptoms: Code execution fails unexpectedly.

Solutions:

• Check runtime configuration
• Verify sufficient memory allocation
• Review Livebook logs
• Try restarting the runtime

Secrets Not Found

Symptoms: System.fetch_env! raises error.

Solutions:

• Verify secret is added in Livebook secrets
• Check secret name matches exactly (case-sensitive)
• Restart runtime after adding secrets

Additional Resources

• Livebook GitHub Repository
• Livebook Official Website
• Livebook Docker Documentation
• Livebook Blog
• Elixir Language
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Livebook on Klutch.sh gives you a powerful, interactive computing environment for Elixir with automatic builds, persistent storage, and secure HTTPS access. The combination of Livebook’s rich features and Klutch.sh’s deployment automation means you can focus on your work rather than infrastructure.

With support for real-time collaboration, smart cells, and app deployment, Livebook transforms how you explore data, document processes, and build internal tools. The BEAM’s unique capabilities for fault tolerance and concurrency make Livebook especially powerful for production workloads.

Whether you’re learning Elixir, exploring data, building dashboards, or automating workflows, Livebook on Klutch.sh provides a reliable, always-available platform for interactive computing.