DOCSEARCHbyAlgolia
Submit Docs

Livebook Documentation

repository·main·Indexed 26 days ago

https://github.com/livebook-dev/livebook

A web application for writing interactive, collaborative, and reproducible code notebooks using Elixir. It supports Markdown, rich interactive results via Kino, and custom runtimes. Documentation covers installation via Desktop App, Docker, or Escript, development setup, security configurations, and detailed environment variables for authentication, networking, and storage.

Tokens
23.7K
Snippets
45
Records
165
Agent score
90%

What's inside Livebook

  1. Overview of Livebook Teams features

    main

    Livebook Teams allows you to deploy notebooks as internal applications and provides a controlled environment for runbooks and production operations. Key capabilities include:

    • App Deployment: Deploy notebooks as internal apps to your infrastructure via the Livebook UI or CLI, and organize them using folders.
    • Access Control: Manage deployment authorization and authenticate users via Livebook Teams, Email-domain (Google, Microsoft, etc.), or OIDC (Okta, Microsoft Entra, etc.).
    • Authorization: Implement authorization based on groups from an OIDC identity provider.
    • Observability: Audit logs are available via STDOUT, recording the identity of the authenticated user, the specific code executed in a notebook, and the timestamp.
    • Shared Resources: Access shared Livebook secrets and shared Livebook file storages.

  3. Understand Livebook Teams Deployment Groups

    main

    A deployment group acts as an organizational and configuration layer that defines a 'deployment context'. It establishes the rules, configurations, and boundaries for where apps are deployed and how they are accessed.

    Key functions of a deployment group include:

    • Logical separation: Allows separating environments (e.g., staging vs. production) or organizational departments (e.g., engineering vs. customer support).
    • Grouping app servers: A deployment group contains one or more app servers.
    • IAM Configuration: It holds the Identity and Access Management (IAM) configuration applied to all app servers within that group.

  4. Understand Notebook Stamping

    main

    Notebook Stamping is a security feature that signs notebook contents with a secret key unique to your machine. This stamp includes permissions for accessing secrets or file system configurations.

    • When opening your own stamped notebooks: Access to secrets and file systems is retained automatically.
    • When opening notebooks stamped by others: A warning is displayed, all access is revoked, and permissions must be explicitly re-enabled.

    Security Warning: Stamping only covers Livebook-managed resources. The code within a notebook still has access to the host machine's environment; always exercise caution when executing third-party code.

  5. Understand Livebook runtime types

    main

    Livebook provides four distinct runtime types for evaluating notebook code, depending on whether you need isolation, access to existing applications, or cloud-managed infrastructure:

    1. Standalone: The default mode. Livebook starts a new, isolated Erlang VM node for each notebook. This allows notebooks to declare their own dependencies using Mix.install/2 without affecting other sessions.
    2. Attached node: Connects to an existing Elixir node managed outside of Livebook (e.g., a running Phoenix application). Code executes within the external node's context, allowing direct function calls to the application. Note: Mix.install cannot be used in this mode; you can only access what is already loaded in the external node.
    3. Fly.io: Provisions a temporary Erlang VM instance on Fly.io infrastructure. It behaves like a standalone runtime but runs on a Fly.io machine that shuts down when disconnected. Requires a Fly.io account.
    4. Kubernetes Pod: Starts a new pod within a Kubernetes cluster. It uses kubectl to proxy a local port to the remote node's distribution port. The pod terminates automatically when the runtime is disconnected.

  6. Understand the security model for shared secrets

    main

    Shared secrets are protected by local encryption to ensure that Livebook Teams servers never have access to the plain text version of your organization's secrets.

    The encryption workflow:

    1. Local Encryption: Livebook encrypts the secret locally on your machine using your unique Teams key.
    2. Encrypted Transmission: The encrypted secret is sent to the Livebook Teams servers.
    3. Synchronized Decryption: When a synchronization occurs, Livebook Teams distributes the encrypted secret to team members. Their local Livebook instances then decrypt the secret using the same Teams key.

  7. Understand Livebook iframe execution and security

    main

    Livebook executes custom JavaScript within iframes. The serving mechanism depends on the protocol used:

    • HTTP: Iframes are served on a separate port.
    • HTTPS: Iframes are served via https://livebookusercontent.com to ensure safe execution.

  8. Relationship between App Servers and Deployment Groups

    main

    The interaction between deployment groups and app servers follows a specific division of responsibilities:

    ComponentResponsibility
    Deployment GroupDefines the 'what': configuration, security rules, and environment.
    App ServerProvides the 'where': the actual compute and runtime location.
    Livebook TeamsOrchestrates the 'how': the mechanism for delivering apps to the app server.

    Cardinality:

    • A deployment group can contain one or more app servers (enabling horizontal scaling).
    • An app server belongs to exactly one deployment group.

  9. Configure Phoenix app for Livebook clustering

    main

    To allow Livebook to cluster with your production Phoenix app, ensure the following configurations are set:

    1. Static Cookie: Set the RELEASE_COOKIE environment variable on your production machines to a static value. This value must match your PHOENIX_APP_COOKIE Livebook secret.
    2. Long Node Names: Enable long node names by setting the RELEASE_DISTRIBUTION environment variable to name in your rel/env.sh.eex file.
    # rel/env.sh.eex

export RELEASE_DISTRIBUTION=name

  11. Test Custom Identity Provider in Development

    main

    To test a custom identity provider locally, clone the Livebook repository and run the following commands from the root folder. You must use the -r flag to load your custom .exs file before starting the server.

    mix setup
LIVEBOOK_IDENTITY_PROVIDER="custom:MyAuth" elixir -r path/to/my_auth.exs -S mix phx.server