Tutorial on how to deploy a Livebook app with Livebook Teams (#3007)

docs/teams/deploy_app.md

@@ -0,0 +1,185 @@
+# Deploy Livebook Apps with Livebook Teams
+
+This tutorial guides you through deploying a Livebook app using Livebook Teams. By the end, you'll have deployed a notebook as an interactive web app running in a local server.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- A [Livebook Teams](https://livebook.dev/teams) account
+- Membership in a Livebook Teams organization
+- Docker installed
+
+If you're not part of a Teams org, here's a [one-minute video showing how to create one](https://www.youtube.com/watch?v=Ox8-JT0JHO4).
+
+## Step 1: Open our example notebook
+
+For this tutorial, we'll use our example notebook that contains a Livebook app.
+
+1. Open Livebook in your browser
+2. Click the **Open** button to open a notebook
+3. Click the **From URL** tab to open a notebook from a URL
+4. Enter the URL of our example app in the notebook URL field: `https://teams.livebook.dev/notebooks/github_stars`
+5. Click the **Import** button
+
+You should see the "GitHub Stars" notebook opened:
+
+![github stars livebook notebook](images/github_stars_notebook.png)
+
+## Step 2: Preview the app locally
+
+Before deploying the app, let's preview what it looks like.
+
+1. Click the **App Settings** icon in the sidebar
+2. Click the **Launch preview** button to run your notebook as an app
+3. Click the URL of your local app preview to open the app
+
+You should see your app running inside Livebook. Something like this:
+
+![app preview](images/app_preview.png)
+
+Notice how the notebook is now running as a web app, with all code hidden, showing just the UI widgets and outputs.
+
+## Step 3: Set up a deployment group
+
+Before you can deploy a Livebook app, we need to configure a [deployment group](teams_concepts.md#deployment-groups)
+for your Teams org. Let's do that.
+
+First, go back to your notebook. Then:
+
+1. Click the **App Settings** icon in the sidebar
+2. Click the **Deploy with Livebook Teams** button
+3. If the notebook is not open within your Teams organization's workspace, you'll be asked to change the workspace to your organization's workspace. Do that if needed and click the "Deploy with Livebook Teams" button again.
+
+You should now see a form to create a deployment group, like this:
+
+![deployment group form](images/deployment_group_form.png)
+
+Let's complete this form to create our deployment group.
+
+1. For the **Name** input, let's use "local test".
+2. For the **Clustering** select, change to "Single instance"
+3. Click the **Add** button
+
+Now we're ready for the final configuration step: setting up a Livebook app server.
+
+## Step 4: Set up a Livebook app server
+
+After completing the previous step, you should see a modal like this:
+
+![app server setup instructions](images/app_server_setup.png)
+
+This modal contains instructions to set up an [app server](teams_concepts.md#app-server). Let's do it.
+
+The easiest way to set up an app server is to run it as a Docker container. You can do that in any
+server infrastructure that runs Docker, such as Fly.io or a Kubernetes cluster.
+
+For our tutorial, we'll set up our app server running in a local Docker container. To do that,
+copy and paste the CLI command provided by Livebook. The instructions look something
+like this:
+
+![CLI command to run an Livebook app server with Docker](images/app_server_docker.png)
+
+> #### Use available host ports {: .tip}
+>
+> You may need to change the host ports in the Docker CLI command if ports
+> 8080 or 8081 are already in use on your machine. Here's how:
+>
+> ```
+> # Instead of using the default host ports, 8080 and 8081.
+> docker run -p 8080:8080 -p 8081:8081 (rest of the command...)
+> ```
+>
+> ```
+> # You can map to different host ports like 9080 and 9081
+> docker run -p 9080:8080 -p 9081:8081 (rest of the command...)
+> ```
+
+Once you run the CLI command in your terminal, Docker will download the Livebook image and run it. Wait until that's done.
+
+Once the container is ready, a Livebook instance will start and automatically connect to your Livebook Teams organization. Livebook will display a message confirming that an app server is now running and connected to your Teams organization, like this:
+
+![feedback message saying the app server is running](images/app_server_setup_message.png)
+
+Now we're ready to deploy our app!
+
+## Step 5: Deploy the app
+
+Once your app server is up and running, return to Livebook. You should see a **Deploy** button like this:
+
+![Deploy button](images/deploy_button.png)
+
+Click the button to deploy your Livebook app to your local app server.
+
+Now let's access the deployed app. If you used the default host port 8080 in the Docker command, access your app server at `http://localhost:8080`. If you used a different port, adjust the URL accordingly.
+
+Once you access it, you will be asked to authenticate. Use the built-in "Sign in with Livebook Teams" authentication mechanism. It will use your Livebook Teams account to authenticate to your app server:
+
+![authentication](images/app_server_authentication.png)
+
+After you sign in, you'll be redirected to your app server, where you'll see the list of deployed
+apps, like this:
+
+![deployed apps](images/deployed_apps.png)
+
+Notice how our deployed app is already there in the list.
+
+To access the app, click on its title. You should now see the app running inside your app server:
+
+![deployed app running](images/deployed_app.png)
+
+That's it, you deployed a Livebook app with Livebook Teams! 🎉
+
+## Deploying new versions of your app
+
+When you want to update your deployed app:
+
+1. Open the notebook and make your changes
+2. Click the **App Settings** icon in the sidebar
+3. Click the **Deploy with Livebook Teams** button
+4. Select your existing deployment group
+5. Click **Deploy**
+
+That's it! A new version of your app will be deployed to your app server.
+
+Try it now by changing the title of your notebook and deploying it again.
+
+## What you've learned
+
+You've successfully deployed a Livebook app with Livebook Teams! Along the way, you:
+
+- Ran a Livebook notebook as an interactive web app
+- Created a deployment group to organize your app deployments
+- Set up a Livebook app server using Docker
+- Deployed your app with a single click
+- Accessed your deployed app through Teams authentication
+- Learned how to update your app by redeploying
+
+You now have the foundation to deploy Livebook apps for your team's internal tools.
+
+## What's next?
+
+Now that you've successfully deployed a Livebook app to a local app server, you might want to explore deploying to an app server running in the cloud. It's very similar to what we did before.
+
+I'll leave this as an exercise for you, the path goes like this:
+
+1. Go to the home page of your Livebook
+2. In the sidebar, click on your Teams workspace
+3. Scroll to the **Deployment groups** section of your workspace, you should see something like this:
+
+![deployment groups of a Teams workspace](images/deployment_groups_inside_workspace.png)
+
+Now, click the **Add deployment group** button and fill in the form to create a new deployment group, like we did in [Step 3](#step-3-set-up-a-deployment-group), but now let's use "staging" as the name of the deployment group.
+
+Once you create this new deployment group, you'll see there's a **+Deploy** link for that deployment group:
+
+![add app server to deployment group](images/add_app_server_to_deployment_group.png)
+
+Click the **+Deploy** link of your staging deployment group to add an app server to it. You should see instructions for different ways to set up an app server:
+
+![instructions to set up an app server](images/instructions_setup_app_server.png)
+
+You can use the Docker instructions to set up an app server in any cloud infrastructure that
+supports Docker. There are also specific instructions for Fly.io and Kubernetes. Use the one you prefer.
+
+> **Want to understand the concepts?** If you'd like to learn more about deployment groups and app servers, check out our [concepts page](teams_concepts.md) after completing this tutorial.

docs/teams/teams_concepts.md

@@ -0,0 +1,43 @@
+# Understanding Livebook Teams concepts
+
+This page explores the key concepts of Livebook Teams.
+
+## Deployment group
+
+A deployment group serves as an organizational and configuration layer for your app servers and Livebook applications. Think of it as defining a "deployment context"—a set of rules, configurations, and boundaries that determine where your apps are deployed and how they can be accessed.
+
+A deployment group serves multiple purposes:
+
+1. **Logical separation**: A deployment group provides logical separation. One example is using different deployment groups for different environments, like staging and production. Or you can use different deployment groups for different departments of a company, like engineering and customer support.
+
+2. **Grouping app servers**: A deployment group contains one or more app servers.
+
+3. **IAM Configuration**: A deployment group contains the Identity and Access Management (IAM) configuration that is applied to all app servers belonging to it.
+
+## App server
+
+A Livebook app server is a Livebook instance configured to act as an application server where you can deploy Livebook apps via Livebook Teams.
+
+It's the same Livebook you can run on your machine, but with a few environment variable configurations that make that instance connect to an organization from Livebook Teams.
+
+Since it's a standard Livebook instance, you can also use it to create, open, and run regular notebooks in addition to serving as a deployment target for apps.
+
+### The app server lifecycle
+
+When you start an app server, it:
+
+1. Connects to the Livebook Teams organization, using its server key to connect to a specific deployment group
+2. Downloads and runs all apps that are deployed to that deployment group
+3. Waits to receive app deployments and configuration changes from its organization and deployment group
+
+This architecture means app servers are essentially "deployment targets" - they don't store apps themselves but receive and run them as instructed by Livebook Teams.
+
+### The relationship between app servers and deployment groups
+
+A deployment group can have one or more app servers, allowing you to scale horizontally. An app server belongs to exactly one deployment group.
+
+Understanding deployment groups and app servers individually is important, but their real power comes from how they work together:
+
+1. **The deployment group defines the "what"**: What configuration, what security rules, what environment
+2. **The app server provides the "where"**: Where the apps actually run, where the compute happens
+3. **Livebook Teams orchestrates the "how"**: How apps get from your Livebook to the app server

mix.exs

@@ -255,11 +255,13 @@ defmodule Livebook.MixProject do
       "docs/deployment/fips.md",
       "docs/deployment/nginx_https.md",
       "docs/teams/intro_to_teams.md",
+      {"docs/teams/deploy_app.md", title: "Deploy Livebook apps"},
       {"docs/teams/email_domain.md", title: "Email domain auth"},
       {"docs/teams/oidc_sso.md", title: "OIDC SSO"},
       "docs/teams/oidc_groups.md",
       "docs/teams/shared_secrets.md",
       "docs/teams/shared_file_storages.md",
+      {"docs/teams/teams_concepts.md", title: "Livebook Teams concepts"},
       "docs/authentication/basic_auth.md",
       "docs/authentication/cloudflare.md",
       "docs/authentication/google_iap.md",