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.

Environments page

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 environment button. This takes you to the create environment page where you can configure your new environment.

New environment settings

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

1. 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. 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.
2. Select a branch from your application's repository to deploy to your new environment.

3. Select if you want the environment to deploy automatically.

4. Select the cluster for this environment where this environment will live.

5. Select any other applications that you want to import into this environment.

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

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.