Our installation procedure involves using the Google Cloud Console to provision a Kubernetes Cluster, and a few IAM accounts and roles. The installation then generates kubernetes yaml which will be applied to that cluster. We can walk you through the installation yourself, or you can create an IAM user with the required permissions and send us the access credentials. We will then manage Saturn for you


  • A machine with Docker.
  • A Google Cloud Platform account that has sufficient permissions to create IAM users and roles, Kubernetes Clusters, Storage Buckets, and Cloud Registries.


  1. Prep our installation working directory.
    mkdir /tmp/install
  2. Create a kubernetes cluster. Navigate to the kubernetes engine page of GCP and click on Create ClusterYou will be taken to the following formYou can choose whatever name you want for the Name (we will choose saturn-cluster). Select Zonal for Location Type, and enter the zone of the VPC or Subnet you wish to connect to. Then click More Options under the default node pool so we can enable autoscaling.To start with, we recommend Node, with a min pool size of and a max pool size of 10. We also recommend bumping the machine type to have 4 vCPUs. Make sure you click save at the bottom.

    Now at the bottom of the cluster form click on Availability, networking, security, and additional features . Under Network, Select the network for your VPC, as well as the appropriate Subnet.

  3. Create a service account for Saturn. Navigate to the service account page of the GCP Console. Click on Create Service Account at the top of the page. In the form, choose a name for the service account, saturn-admin. You should grant the role of Storage Object Admin. At step 3, please click on Create Key and select JSON. Save the key to /tmp/install/gcp.json
  4. Setup the Container Registry. Activate the Container Registry API. Then we have to push an image to the registry in order to create a storage bucket.
    docker pull registry:2docker push${project-id}/registry:2
  5. Setup Google Cloud Storage permissions. Navigate to the Cloud Storage browser. You should see a bucket for the docker registry. artifacts.${project_id} Click the menu button on the right of the bucket in order to edit bucket permissions.Click on Add Member, Select the service account we just created, and assign the role of Storage Object AdminCreate a new bucket for Saturn. Choose a name like saturn-data, and select Zonal, and choose the region for your kubernetes cluster. You don’t need to add permissions here, we can do that on the previous screen just like before. Again, add the service account as Storage Object Admin
  6. write the configuration file to /tmp/install/gcp-config.yaml
      - display: 'Micro - 0.5 cores - 1 GB RAM'
        cores: [0.5, 1.0]
        memory: ['750M', '1G']
        name: 'micro'
      - display: 'Medium - 2 cores - 4 GB RAM'
        cores: [0.5, 2.0]
        memory: ['3G', '4G']
        name: 'medium'
      - name: "3G"
      - name: "20G"
      - name: "60G"
    saturn_bucket_name: "${saturn-data-bucket-name}"
    docker_host: "${project-id}"
    domain: "${saturn-domain}"
    use_ssl: False
    admin_email: ${admin_email}"
      port: 587
      user: "${smtp-email-address}"
      password: "${smtp-password}"
    license_id: "${license-id}"

    admin_email – Your email address.
    sizes – The size of Jupyter instances users get access to. cores and memory are expressed as upper and lower bounds. These do not have to match up identically with the worker groups, however if you have memory and cpu requests here that exceed your largest worker size, they won’t be runnable.
    disk_space – Choices for home directory size in Saturn.
    saturn-data-bucket-name – the bucket to store data.
    name-of-GCR-docker-host – Name of GCR host for your account. For example ours is
    saturn-domain – The domain you want to host Saturn. For example, if you choose, Saturn will run on, JupyterHub will run on, and an anonymous JupyterHub(for publishing) will run on
    smtp-email-address, smtp-password, license-id – We will give you these values. If you would like – we can configure this such that you use your own smtp server, however by default we manage smtp for you.

    After completeing the configuration file, please create a directory, /tmp/install and write the configuration file into that location as /tmp/install/config.yaml

  7. Install Saturn in to the resulting Kubernetes cluster.
    Create kubernetes yaml:

    docker run -v /tmp/install:/root saturncloud/saturn-gcp:2.0 python kube /root/config.yaml

    Authenticate with the kubernetes cluster

    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "gcloud container clusters get-credentials ${cluster-name}"

    Install nginx ingress, the cluster autoscaler, and Saturn into kubernetes

    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "kubectl apply -f /root/kube/cluster-autoscaler"
    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "kubectl apply -f /root/kube/nginx-ingress"
    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "kubectl apply -f /root/kube/saturn"
  8. Finish DNS settings. The above steps will create a load balancer where Saturn Cluster will listen to http requests. Execute
    docker run -it -v /tmp/install:/root saturncloud/saturn-gcp:2.0 /bin/sh -c "kubectl get service saturn-nginx-ingress-controller"

    The output will look like

    NAME                              TYPE           CLUSTER-IP   EXTERNAL-IP  PORT(S)                      AGEsaturn-nginx-ingress-controller   LoadBalancer   80:31009/TCP,443:30353/TCP   32s

    Then add a wildcard CNAME dns entry for the domain you decided to use for Saturn. In our case, that is:
    mapping to

  9. Add users You should receive an email to reset the password of the admin account admin . Please reset the password, and then login to Saturn. Once you are logged in, please login to the admin panel (it should be under /admin/setup, but there should be a link on the side of your dashboard). Here you can create new users. They will each get password reset requests.