Create an environment

When you create a new Release application, Release automatically creates your first ephemeral environment. To view an application's environments or to create new environments, navigate to the application's Environments tab.

Free accounts are limited to two environments at a time. If you're on a free account and already have two environments, you'll need to delete one before proceeding with this guide. To create more than two environments, upgrade your account.

How to create a new environment

On the Environments page, click the Create new environment button. This opens a popup with settings for your new environment.

Let's take a look at each of these options:

  1. Select a branch from your application's repository to deploy to your new environment.

  2. Select an environment type: Choose whether the new environment should be ephemeral (lasting for a limited time – seven days by default) or permanent (lasting until manually destroyed). To learn more about ephemeral and permanent environments, see our page about environment expiration.

  3. If you're creating a permanent environment, select whether this is a production environment. If you're just testing out a new environment, leave this option unchecked. Release protects production environments from accidental deletion.

  4. If you're creating a permanent environment, enter an environment name. Release will convert this name to lowercase and remove spaces. Ephemeral environments get an autogenerated name.

  5. Click on Advanced Options if you want to override any default settings. We recommend leaving the default values, but you can take a look at what these options do.

  6. Select the context for this environment. If you are a self-hosted user and have more than one Kubernetes cluster in your Release account, the context determines which cluster Release will use for this environment.

  7. Select a domain to use for this environment. This is useful if you have more than one domain attached to your selected cluster.

  8. Under Override Build Images, you can enter specific Docker images to deploy to your services. By selecting a specific Docker image for a service, the image for this service will not be updated when you push new code to your branch. By default, Release will pull the latest image for each service.

  9. Optionally, for ephemeral environments only, override your environment's lifespan, measured in days and hours. By default, ephemeral environments will last for seven days. Leave days and hours as zero to use the default expiration.

  10. Lastly, click Create environment.

Release will now create your new environment and redirect you to a page that shows you deployment progress in real time.

What happens after you create an environment

Release goes through four stages for each new environment.

1. Build

During the build stage, Release pulls a branch from your application's repository, then runs docker build for each service. After building new Docker images, Release pushes the images to a private container registry.

2. Setup

Next, Release sets up your new environment by creating the required nodes and other resources, setting quotas, pulling Docker images, and deploying containers, and starting services with docker run.

3. Diagnostics

Release then sets up a health checker to monitor your deployed services.

4. Traffic routing

Finally, Release routes network traffic to your new environment by updating a routing table for your application.

How to use your new environment

Your environment should now be deployed and ready to use.

To view the environment's details page, visit your application's Environments page and click on the new environment you created.

From the Environment Details page, you can view URLs for your services, change settings for your environment, and see details about running instances.

Test it out: To see how Release builds and redeploys your application, push a code update to your repository in the branch tracked by this environment, then visit the Deployments tab in Release.

Last updated