Saturn can deploy scheduled data pipelines, models, dashboards, and arbitrary web applications


Deployments are custom-defined applications that run inside your Saturn’s Kubernetes cluster. A deployment can be a model, a dashboard, or another application. Deployments use the same libraries, conda environment, and image that your Jupyter instances use, meaning that they can (but don’t need to be) developed inside of Jupyter Lab.

Creating and Deploying

Deployments are tied to a Project. Files within the working directory (default: /home/jovyan/project) are included in the same place in a Deployment’s container, and that directory is set as the starting directory.

Deployments are assiged a public-facing hostname once created. Port 8000 will forwarded from the load balancer to the deployments’ container(s). The server or process should also be bound to (the below example does not require this - some frameworks, such as Flask, will bind to by default).

For example, using the following script at project/

import http.server
import socketserver
from http import HTTPStatus

class Handler(http.server.SimpleHTTPRequestHandler):
    def do_GET(self):
        self.wfile.write(b'Hello Saturn!')

httpd = socketserver.TCPServer(('', 8000), Handler)

A Deployment can be created from the your Project’s details page in your Saturn dashboard. After selecting the project you would like to add a Deployment to, click the “Create a Deployment” button or + in the Deployments section of the Project’s details page.

To run the example above, the command is simply python - the container starts in the working directory (default: /home/jovyan/project). Once the settings have been set as desired, click Create. The new Deployment will show in the Deployments section of the Project’s details page:

Initially, the status will be stopped. Click the play icon to start it.

Accessing a Deployment

In the deployment’s details, a URL is shown. This is the URL for the deployment - clicking it will open the deployment. Deployments are protected by an internal authentication layer. When accessed, the user’s Saturn session is verified. If the user is not signed in, they will be prompted to sign in. Currently, any signed-in Saturn user can access the deployment.


Anyone who is logged into your Saturn installation can view your deployment. We run an http proxy that can check whether someone is logged in, and grant them access to the underlying resource


The same logic applies for models, except that it’s much easier to use our API tokens to log in. Every Saturn user service (Jupyter/Dask/Deployments) has an API token passed as an environment variable that can identify who owns the service, and what the service is. If you pass that token in http headers, you will be granted access to the resource

import requests
import os

url = ""
response = requests.get(
    headers={"Authorization": f"token {SATURN_TOKEN}"}

Updating and Redeploying a Deployment

When a Deployment is created, the current HEAD commit from its project’s git repository is used for all containers, no matter how many there are. This means that the project can be freely modified and updated without a need to worry about breaking deployments, but it also means that deployments do not automatically update. To sync a deployment’s containers up to the latest code, click the “Sync” button in the deployment’s details.

The deployment’s command, instance count, and instance size can be modified by clicking the “Update” button. Doing so will also bring the deployment’s containers up to the latest code from the project.


For general troubleshooting, the deployment’s logs can be viewed by clicking the “Logs” button in the deployment details.

The Deployment never gets to “Ready” status

The most likely cause of this is that deployment’s containers are either crashing, or exiting too quickly. Kubernetes expects deployments’ containers to be long-running processes - if the deployment’s code is a simple short task, such as something that pulls work from a queue, it may need to be changed to a loop.

If the containers are crashing, errors should be shown in the deployment’s logs.

The Deployment’s status is “Ready”, but accessing the resource gives a status 502

The most likely cause of this is that nothing is bound to port 8000 within the deployment’s containers. 8000 is the only forwarded HTTP port - applications need to bind to it to be accessible. Another possibility is that the server is bound to and not - it needs to listen on all addresses to be accessible from outside of the container.

For any other issues, please contact