Our installation procedure is a series of commands executed inside a docker container. We can walk you through the installation yourself, or create an IAM user with the required permissions and send us the access credentials. We will then manage Saturn for you. The installation generates terraform yaml which provisions an EKS cluster in your AWS account, and then generates kubernetes yaml which will be applied to that cluster.


  • A machine with Docker
  • An AWS account that has access to the following permissions
        "Version": "2012-10-17",
        "Statement": [
                "Sid": "admin",
                "Effect": "Allow",
                "Action": [
                "Resource": "*"
                "Sid": "s3",
                "Effect": "Allow",
                "Action": "s3:*",
                "Resource": ["arn:aws:s3:::saturn*/*", "arn:aws:s3:::saturn*"]
                "Sid": "ecr",
                "Effect": "Allow",
                "Action": "ecr:*",
                "Resource": "arn:aws:ecr:*:*:repository/saturn*"


  1. write the configuration file
    region: "${cloud-region}"
    vpc_id: "${vpc-id}"
      - "${public-subnet-id1}"
      - "${public-subnet-id2}"
      - "${private-subnet-id1}"
      - "${private-subnet-id2}"
      - "${saturn-private-subnet-id}"
      - "${saturn-zone}"
      - name: medium
        asg_min_size: 1
        asg_max_size: 5
        asg_desired_capacity: 1
        instance_type: t3.medium
      - name: xl
        asg_min_size: 0
        asg_max_size: 5
        asg_desired_capacity: 0
        instance_type: t3.xlarge
      - 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: "${name-of-ECR-docker-host}"
    domain: "${saturn-domain}"
    use_ssl: False
    admin_email: ${admin_email}"
      port: 587
      user: "${smtp-email-address}"
      password: "${smtp-password}"
    license_id: "${license-id}"

    EKS requires at least 2 zone – however Saturn generally uses only 1 zone. Saturn persists user home directories in EBS, which is limited to a single zone, so high availability does not help. For the configuration, we need the VPC id, and public and private subnet ids for each zone in your VPC. You also need to pick a specific zone for Saturn.

    cloud-region – The region your saturn installation will run in.
    For example, we typically run in us-east-2.

    admin_email – Your email address.

    vpc-id – The ID of the VPC you wish to install Saturn into.

    public-subnet-id[1-3] – The ID of the public subnets in your VPC

    private-subnet-id[1-3] – The ID of the private subnets in your VPC

    saturn-private-subnet-id – The ID of the private subnet that you want for Saturn

    saturn-zone – The zone of saturn-private-subnet-id

    worker_groups – The workers you wish to use for Saturn. The example uses 2 worker groups. The desired capacity of the first group should be 1.

    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 – Saturn provision an s3 bucket to store data.

    name-of-ECR-docker-host – Name of ECR 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

  2. Provision AWS resources
    Please create a directory on your machine /tmp/install, and copy
    the aws config that has sufficient credentials into /tmp/intall/.aws
    To create terraform yaml, please execute:

    docker run -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 python cluster /root/config.yaml

    This sets up terraform yaml in /tmp/install/terraform

    To provision the EKS cluster, please execute the following. It may take 10 minutes to complete:

    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 /bin/sh -c "cd /root/terraform/cluster; terraform init; terraform apply ."

    At this point we strongly recommend that you create a git repository with the contents of /tmp/install/terraform You will need this later if you wish to tear down these resources, or update them

  3. Install Saturn in to the resulting Kubernetes cluster.Create kubernetes yaml:
    docker run -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 python kube /root/config.yaml

    Authenticate with the kubernetes cluster

    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 /bin/sh -c "aws eks update-kubeconfig --name saturn-cluster"

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

    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 /bin/sh -c "kubectl apply -f /root/kube/cluster-autoscaler"
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 /bin/sh -c "kubectl apply -f /root/kube/nginx-ingress"
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 /bin/sh -c "kubectl apply -f /root/kube/cluster"
    docker run -it -v /tmp/install:/root saturncloud/saturn-aws:2.6.0 /bin/sh -c "kubectl apply -f /root/kube/saturn"
  4. 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-aws:2.6.0 /bin/sh -c "kubectl get service saturn-nginx-ingress-controller"

    The output will look like

    NAME                              TYPE           CLUSTER-IP   EXTERNAL-IP                                                               PORT(S)                      AGE
    saturn-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

  5. 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.