Getting Started


In this documentation, we will explain how to deploy the Nimbus self-host solution to your cloud.
First, we will walk you through the basic concepts and components you will need to deploy/set up on a high level. Then we will help you ensure that you have all the prerequisites/permissions to perform deployment operations. Once we confirm the prerequisites are met, we can follow the detailed instructions to deploy/set up each main component. Finally, we will show you how to get your first workspace up and running.


Conceptually, Nimbus contains two planes - the data plane and the control plane.
  1. The Data Plane contains all the needed resources to make β€œworkspaces” work. That includes the EC2 instance, security group (for each EC2), AMI (for both base images and cache images), volumes, etc. Those are also the place that engineers will spend the most time on, such as writing code, sharing demo
  1. The Control Plane serves both frontend, backend, and database. That also includes some supporting resources to make the app work - such as a load balancer.

Main components:

In this section, we will explain on a high level the main components of the Nimbus self-host solution. More details about each component can be found in the related instruction documentation.


The domain that will be used to host webapp and workspace hostname. All you need is the AWS permission to self-deploy the solution. You can find details below.

Control Plane:

You can use AWS EC2 (or EKS) to host the Nimbus control plane, including frontend, backend, DB, and so on.
Deployment Prerequisites:
  • AWS permission to launch EC2 or EKS according to this LIST

Okta integration:

The SSO integration authenticates internal engineers to the self-host solution.
Deployment Prerequisites:
  • Permission to create the okta app

Github Action:

The CI that runs `terraform apply` to provision and configure workspaces
Deployment Prerequisites:
  • Permission to create a Github repo and related Github Actions on that repo
  • Permission to create a Github app
  • AWS credentials from a role with permission to perform terraform apply. In other words, the permission should match the operations you want to perform based on your Terraform.


Once the prerequisites are confirmed, we are ready to start the deployment. It should take about 45 min to complete the entire process. However, most of the time should just be waiting for certain services, like the EKS, to be ready.


Decide the subdomain, for example, nimbus.company.com. No actions are required at this stage but this will be used for later steps

Control Plane:

In the documentation below, we will walk you through the process step by step to deploy the Nimbus control plane and configure the related network settings. At the end of this step, you will have the Nimbus self-host solution running on your cloud. This entire process should take about 5 to 10 minutes.
Note: We can also deploy on EKS. Please reach out to support@usenimbus.com for detailed instructions


In the documentation below, we will walk you through the process step by step to integrate your Okta account with Nimbus. At the end of this step, you will be able to log in to the self-hosted solution you just deployed and start to create your first template and workspace.

Github App:

Github app is used for Nimbus to authenticate users to your own Github-related resources

Github Action:

In the documentation below, we will walk you through the process step by step to set up your Github Action as the CI so you can create workspaces from Terraform. At the end of this step, you will be able to create a workspace from a default Terraform template that we set up for you. Starting from here, you can iterate and fully leverage Terraform on Nimbus.

VSCode Configuration:

In order for the Nimbus VSCode extension to work with a self-hosted Nimbus solution we need to update the default Nimbus URL in VSCode. The following documentation shows you how to do so.