Create a Domino Environment

This guide shows you three ways to create a new Domino Environment, whether you want to make a core Domino environment, base it on an existing environment, or start from a custom setup.

Tour the new environment window

Name: The name you give your environment.
Description (Optional): Use this to record details about your environment.
Base Environment / Image: These are the options for a base environment/image:
1. Start from an existing Environment: Base your new environment on an existing Domino environment.
2. Active (auto-rebuilds): For an existing environment, keep this selected, or choose a specific revision from the menu.
3. Start from a custom base image: Input a URI to build a custom environment.
Supported Clusters: Lists the currently supported types of clusters.
Visibility: Choose a visibility level: Private, Available to an Organization, or Globally Accessible (admin only).
Revision Behavior: Auto-assigns the latest revision as active.
Customize before building: Use this to add custom features to your environment.
Create Environment: Validates and creates your new environment.

Create environment based on Domino core environment

Domino comes with the Domino Core Environment installed, but you can create a new Domino Environment using the available environment images.

Go to Govern > Environments and click + Create Environment.
Fill in the following fields:
1. Name: Name your environment according to the naming convention of your organization.
2. Description (Optional): Enter a meaningful description of the environment. For example, you could add details like the OS, Python version, and whether the environment uses Jupyter, JupyterLab, VS Code, etc.
Choose Start from an existing Environment for your Base Environment / Image.
1. The global default for your environment is pre-selected.
2. Scroll until you can select the Domino Core Environment.
3. Active (auto-rebuilds): keep this selected, or choose a specific revision from the menu.
Choose an option for any Supported Clusters.
Decide on your environment’s Visibility level: Private, Available to an Organization, or Globally Accessible (admin only).
Click Create Environment. The Revisions tab for the environment opens.

To customize the environment to enable tools, run scripts, or manage environment variables, click Customize before Building and use the Customize your Environment guide. You can also click Edit Definition to customize the environment later.

Create environment based on existing environment

You can create a new Domino Environment by duplicating existing environments, or by choosing a base environment from the Start from existing environment menu. After building or editing an environment, use the Auto-assign next new revision as Active toggle in the Revisions tab to control which revision is active. When enabled, the latest successful build becomes Active automatically. When disabled, the environment stays on the current Active revision, even as new ones are built.

Suppose your environment updates automatically due to a subscription, but you have locked its Active revision to a specific version. In that case, you see a notice when the base environment’s Active revision changes. This reminds you to consider updating your environment’s revision. You can keep a chosen version of your environment as Active while still receiving updates on the base environment. This lets you test the new version before connecting your Jobs, Apps, and Model Endpoints to it. Please note that archived images are not rebuilt automatically.

Create environment by duplication

To create a new environment by duplicating an existing environment:

Go to Govern > Environments.
Choose the environment you want to copy and click the three dots on the right.
Choose Duplicate Environment from the menu.
Rename it by clicking the edit icon and then entering when done.
You can edit other fields quickly to customize them:
1. Edit Description: Click Update when you are done with the description.
2. Edit Visibility: Click Update Visibility when finished.
Click Customize before building or Create Environment.

Use the Customize your Environment article for guidance to enable tools, run scripts, or manage environment variables.

Create environment from existing environment

When you create a new environment based on an existing one or change the settings of an environment, you have two options for building it:

You can create it based on a specific version of the base environment. You can change this on a later revision of your own.
You can set it to update automatically by linking it to changes in the base environment’s Active revision. If the base environment changes its Active revision, your environment automatically builds a new revision based off of it.

To create a new environment by using an existing environment as the base:

Go to Govern > Environments.
Select Create Environment.
Choose the environment you want to use as the base from the menu.
1. Active (auto-rebuilds): keep this selected, or choose a specific revision from the menu.
Name your new environment.
Description (Optional): Enter a description of the environment.
Choose a Visibility level for your environment.
Click Create Environment. The Revisions tab for the environment opens.

Use the Customize your Environment article for guidance to enable tools, run scripts, or manage environment variables.

Create environment based on custom images

Choose your custom Docker or container image before creating a new environment and copy the URI.

Go to Govern > Environments and click +Create Environment.
Fill in the following fields:
1. Name: Name your environment according to the naming convention of your organization.
2. Description (Optional): Enter a meaningful description of the environment. For example, you could add details like the OS, Python version, and whether the environment uses Jupyter, JupyterLab, VS Code, etc.
Choose Start from a custom base image for your Base Environment / Image.
1. FROM: Paste the custom Docker or container image URI here.
2. Optional: Review the information about the Automatically make compatible field.
Choose an option for any Supported Clusters.
Decide on your environment’s Visibility level: Private, Available to an Organization, or Globally Accessible (admin only).
Click Create Environment. The Revisions tab for the environment opens.

Set supported CPU architectures

Each environment revision declares the CPU architectures it supports: amd64, arm64, or both. When an execution starts, Domino checks that the environment supports the CPU architecture of the selected hardware tier and rejects the execution if it doesn’t. For on-demand clusters, Domino runs the same check against the cluster’s head and worker hardware tiers. If a revision doesn’t declare architectures, it inherits the architectures declared on its base environment. If neither declares architectures, the revision supports amd64, so existing environments keep running on their current hardware tiers. Declare architectures with the v2 environments API:

POST /api/environments/v2/environments creates an environment. Set the architectures array on the initialRevision object.
POST /api/environments/v2/environments/{environmentId}/revisions creates a revision of an existing environment. Set the architectures array at the top level of the request body.

Domino returns a 400 response when the architectures array contains a value other than amd64 or arm64. In v2 request bodies, the dockerfileInstructions, preSetupScript, postSetupScript, preRunScript, and postRunScript fields are nested under a buildConfiguration object. The beta environments endpoints are deprecated and don’t support architectures. Example request:

import requests
import json

url = "https://your-domino-url/api/environments/v2/environments"

payload = json.dumps({
  "name": "multi-architecture-environment",
  "visibility": "private",
  "addBaseDependencies": True,
  "initialRevision": {
    "image": "quay.io/example/base-image:latest",
    "architectures": ["amd64", "arm64"]
  }
})
headers = {
  'X-Domino-Api-Key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

To read the architectures a revision supports, get the environment with GET /api/environments/v1/environments/{environmentId} and check the architectures array on each revision.

Archive an environment

You can archive environments as long as they are not the default environment for a project. Archiving an environment does not affect reproducibility; executions based on it still run.

Go to Govern > Environments.
Choose an environment from the list.
There are two ways to archive an environment quickly:
1. You can click the 3 dots within the list and choose Archive Environment.
2. Choose Archive Environment from the menu. You can also archive from any tab within the Environment details.

Next steps

Customize your Environment to enable tools, run scripts, or manage environment variables.
Set default Environments establishes a starting point for all new projects or an environment for a specific project.
Our Best Practices guides you in setting up and maintaining your Domino environments.
Use AI coding assistants to enhance your coding in a Domino Environment.

Core Concepts

Features

Create a Domino Environment

Tour the new environment window

Create environment based on Domino core environment

Create environment based on existing environment

Create environment by duplication

Create environment from existing environment

Create environment based on custom images

Set supported CPU architectures

Archive an environment

Next steps

​Tour the new environment window

​Create environment based on Domino core environment

​Create environment based on existing environment

​Create environment by duplication

​Create environment from existing environment

​Create environment based on custom images

​Set supported CPU architectures

​Archive an environment

​Next steps

Tour the new environment window

Create environment based on Domino core environment

Create environment based on existing environment

Create environment by duplication

Create environment from existing environment

Create environment based on custom images

Set supported CPU architectures

Archive an environment

Next steps