Configure Dev Environment for Project
To provide the best possible experience, a dev environment must be pre-configured for your project. A configured environment includes all necessary tools and runtimes, IDE indexes, and other data required by the project, e.g., environment variables, project dependencies, and so on. As a result, a user can start working on their project right after a dev environment is created.
Configuration steps
Dev environment configuration includes the following steps (you can skip any of these steps depending on your needs):
Specify a dev environment instance type
Dev environments come in three different types that differ by available compute resources.
You can specify a default IDE and a particular IDE version for the project.
The image must include the tooling and runtimes required by the project. You can use an image from Docker Hub (or other registries that doesn't require authentication), from a Space Packages registry, or even define a custom image using a
Dockerfilefile in the project repository.If you skip this step, the created dev environments will use the default image.
A warm-up snapshot contains pre-built project data. By default, the snapshot contains only IDE indexes, but it can also contain additional project data like dependencies, build caches, and so on. You can automate creating a warm-up snapshot: Space can create it on schedule or on commit push.
If you skip this step, Space will create dev environments without warm-up data.
Define environment variables that are required for development in a dev environment.
Specify user secrets and parameters required for development
A dev environment might require sensitive user data, e.g. credentials to an external service. User secrets and parameters are available in a dev environment as environment variables.
Configure JVM options for IntelliJ-based IDEs
You can change the configuration of Java Virtual Machine (JVM) your IntelliJ-based IDE runs on.
Default dev environment
Configuring a dev environment is optional. If you skip it, Space will use a default dev environment: the environment based on the default Docker image with no additional project data.
The default Docker image is based on Ubuntu OS and includes Git, curl, Docker, Docker Compose, Kubernetes, Google Cloud support, Open JDK, Python, PHP, .NET SDK, Ruby, Go, Node.js, npm, yarn, and other tools.
Default image Dockerfile:
You can use this Dockerfile as a basis for creating your own image and hosting it in Space Packages. Learn more
Devfile configuration file
To configure a dev environment for a project, you should use a devfile. Devfile is an open specification that uses YAML formatting for configuring and running build environments. Currently, Space supports only a feature subset of the 2.2.0 specification (the supported features are fully covered by the documentation topic you're currently reading).
A project may have a single devfile.yaml file or a number of *.devfile.yaml files located in the .space directory in the repository root. When users create a dev environment, they can choose from all devfiles available in the project. Dev environment settings are taken from the selected devfile.
Here's an example of a devfile.yaml file:
Specify a configuration name
To help users distinguish a partcular dev environment configuration in a project with several devfiles, specify a name for each configuration. If you don't specify a name, the configuration will be named after the IDE it uses.
To specify the name, use the metadata.name parameter:
Users will see this name when selecting a devfile for a newly created dev environment.
Specify a default dev environment instance type
Dev environments can run on three different virtual machine instances: regular (4 vCPUs, 8 GB), large (8 vCPUs, 16 GB), and extra large (16 vCPUs, 32 GB). Learn more about dev environments billing.
To specify a default instance type, use the space.instanceType parameter. Users can choose another instance type when creating a dev environment.
Specify a default IDE
You can use the following IDEs from JetBrains in a dev environment: Fleet, IntelliJ IDEA, WebStorm, PyCharm, RubyMine, CLion, GoLand, PhpStorm, and Rider *. To get information about available IDEs, Space uses the JetBrains Toolbox App update service. You can view the available IDEs, IDE versions, and version release states (e.g., Release, EAP, and so on) on the dev environments administration page.
Using the space.editor parameters, you can specify a default IDE, IDE version, and version release state. Users can change any of these settings when creating a dev environment. When warming up a dev environment, Space will build IDE indexes for the IDE and IDE version specified in the devfile.
Default IDE version
If not specified in a devfile, the default IDE version is always the latest available release version. This is the organization-wide default. To change it, a user must have the Edit dev environments settings global permission (for example, this can be an administrator with the System Admin role).
To specify the default IDE version for organization dev environments
Open Administration, then Dev Environments.
Under Default IDE versions, find the required IDE and choose a new default version.
Use JetBrains Rider in a dev environment
If you want to use a dev environment with JetBrains Rider, you must additionaly specify a path to the solution file. To specify the path, use the projectRoot parameter. For example:
Specify an image for the dev environment
A dev environment runs in a Docker container. If you don't specify an image in a devfile.yaml, Space will use the default image. As a custom image, you can use an image from Docker Hub (or other registries that doesn't require authentication), Space Packages, or create an image from Dockerfile each time a user creates a new dev environment. To specify the image, use the project's devfile.
- Image requirements
OS: any glibc-based Linux distribution (for example, CentOS 7+, Debian 9+, Ubuntu 20.04+).
Tools: Git, OpenSSH (if you want to use a remote Git repository), lsof (if you need port forwarding in the IDE).
The container must run as
root(there must be no non-root users inDockerfile).
- Container image vs warm-up snapshot
In some cases, you might face a dilemma where to put a certain preparation step: to the container image or to the environment warm-up. For example, your project requires an SDK. To get the SDK, you run
curl - o sdk.zip $SDK_URL && unzip sdk.zip. Where do you put this line: to theDockerfileor to the warm-up script?Our recommendation is to use the
Dockerfileonly to configure the environment. All binary dependencies should go to a warm-up script. So, in the example above, the best solution would be to get the SDK in a warm-up script.
In the components.container.image parameter, specify the full image URL.
Important: the Space Packages registry must either belong to the same project where you configure a dev environment or be attached to this project.
A dev environment can use a custom Dockerfile for its container image. The Dockerfile can be located anywhere in the project repository. Note that in this case, Space will build the image each time a user creates a new dev environment. To reduce startup time of the dev environment, we recommend that you build the image once and publish it to the project's Space Packages registry.
Open the project source code and create a
Dockerfile, for example, in thedockerdirectory.Edit the
Dockerfileto configure the image.For example, an image for a Java project:
FROM ubuntu:20.04 ENV DEBIAN_FRONTEND=noninteractive ENV LC_ALL=C.UTF-8 RUN apt-get update RUN apt-get install -y \ git \ openjdk-11-jdk \ && rm -rf /var/lib/apt/lists/* ENV JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64Open the project source code and open the project's devfile. If it doesn't exist, create a new one, for example,
.space/devfile.yaml.In the devfile, specify the path to a Dockerfile (
uri) and, optionally, to the Docker context (buildContext). You must specify both paths relative to theprojectRoot. For example:schemaVersion: 2.2.0 attributes: space: instanceType: large editor: type: Idea components: - name: image-build image: # (Required) imageName: my-image:latest dockerfile: # (Optional) path to Docker context relative to projectRoot # by default, projectRoot is repository root buildContext: docker # (Required) path to Dockerfile relative to projectRoot uri: docker/Dockerfile args: - 'ARG1=A' - 'ARG2=B'Commit and push the changes.
You can use images not only from Docker Hub but from any public registry that doesn't require authentication. In case of an image from Docker Hub, you can specify only the image name. For other registries, you must specify the full image URL.
Warm up the dev environment
Dev environments can significantly increase the speed of development by removing the IDE warm-up phase: a period of time when the IDE builds indexes, and does other background activities like resolving project dependencies. You can put all these routines into a dev environment warm-up and run it on schedule or on commit push. The result of the warm-up is a disk snapshot (or warm-up snapshot) that is then mounted to a dev environment. Make sure the warm-up is run regularly: The fresher the index data is, the faster a dev environment will be ready for work.
To configure warm-up, use the warmup parameter. For example:
How Space runs the warm-up
When the warm-up is triggered, Space creates a run environment based on the devfile settings: the specified container image, environment variables, and so on. In this warmup environment, Space:
Checks out the project source code.
(Optional) Runs your custom shell script if you specified it in the
warmup.scriptblock.Builds project indexes for the IDE specified in the devfile.
Project indexes are specific for each IDE and most often for each IDE version. For the warm-up, Space uses the IDE version specified in the
editor.versionparameter of the devfile. If the version is not specified, the warm-up will create indexes for the default IDE version.If you don't want the warm-up to build project indexes, specify:
warmup: indexing: false
How to trigger the warm-up
By default, warm-up triggers are disabled for a project. To enable the triggers, open project settings, and on the Dev Environments tab, enable warm-up triggering for the required project repository.
There are three ways to trigger the warm-up: manually in the Space UI, by schedule, and by pushing a commit to the project repository.
In the sidebar, select Dev Environments.
Open the Warm-up Snapshots tab and select the required repository and branch.
Click Run warm-up for {your-defvile}. If the project has more than one devfile, click Show all detected devfiles and Run warm-up for the required devfile.
You can check the warm-up execution state on the project's Dev Environments page.
The schedule trigger runs the warm-up in the default project branch (which is main by default). The schedule warm-up triggers specified in other branches don't trigger the warm-up.
In schedule, use the UTC timezone and the crontab format (MIN HOUR DAY MONTH DAYOFWEEK):
The gitPush trigger runs the warm-up after a user pushes a commit to the project repository.
You can limit the scope of gitPush so that it triggers not on any change in the project repository but only on changes in particular branches, tags, directories, or files.
Filter by branch
By default, when a commit is pushed to the repository, Space tries to run the warm-up from the devfile.yaml file in the same branch where the changes were committed. For example, if you push changes to the cool-feature branch, Space will try running the warm-up from the devfile.yaml file in this revision in the cool-feature branch.
branchFilter lets you specify the list of branches where Space should run the warm-up. For example, the following warm-up will run only on changes in the my-feature branch:
If a change is pushed to the my-feature branch, this warm-up will start in the my-feature but not in the main or any other branch. If a change is pushed to the main branch, none of the warm-ups will start – Space will try to run the script in the main branch, but it has the branchFilter that prevents this.
branchFilter supports the following filtering rules:
The filter supports the
includeandexcluderules.You can use asterisk (
*) wildcards, e.g.include: - 'refs/heads/release-*'The filter supports include and exclude rules for regular expressions, e.g.
includeRegex: - 'release-\d+' excludeRegex: - 'release-221'Exclude rules have priority over include rules.
branchFilteralso lets you specify filters by Git tags, e.g.# run only if there's a release tag # e.g., release/v1.0.0 include: - 'refs/tags/release/*'For example:
schemaVersion: 2.2.0 attributes: space: editor: type: Idea warmup: startOn: - type: gitPush branchFilter: # add 'main' and all '222.*' tags include: - 'refs/heads/main' - 'refs/tags/222.*' # add all branches containing 'feature' includeRegex: - 'feature' # exclude test-feature exclude: - 'refs/heads/test-feature'
Filter by path
pathFilter lets you specify paths to certain directories and files. For example, the warm-up below will run only if there is a change in the Main.kt file:
You can use pathFilter to fine-tune branchFilter: Space first checks if there's a change in a particular branch and only then it applies a pathFilter. If branchFilter is not specified, pathFilter works only within the current branch (the one with the committed changes).
pathFilter supports the following filtering rules:
The warm-up will run if at least one file matches the specified filter.
The filter supports the
includeandexcluderules.You should specify path relative to the project root directory.
You can use asterisk (
*) wildcards for matching the files only inside the current directory and double-asterisk (**) for a recursive match. For example,src/tests/*matches all files inside thetestsdirectory. Thesrc/tests/**matches all files insidetestsand all its subdirectories.A more specific path has priority over less specific paths, e.g.
src/tests/MyTests.kthas priority oversrc/tests/**.For example:
schemaVersion: 2.2.0 attributes: space: editor: type: Idea warmup: startOn: - type: gitPush branchFilter: include: - 'refs/heads/main' pathFilter: exclude: # exclude 'targets/main' dir - 'targets/main/**' include: # include everything from 'targets' dir - 'targets/**' # include all 'Main.kt' files in the project # As this rule is more specific, # 'Main.kt' will be included even if # it's located in 'targets/main' - '**/Main.kt' # include all '.java' files from the 'common' dir - 'common/**/*.java'
Manage warm-up snapshots
Space stores only the latest warm-up snapshot for each combination of an IDE and a Git branch. An IDE version is not taken into account. For example, a project has two branches: main and feature-branch. Suppose some developers use JetBrains Fleet and some use IntelliJ IDEA. There can be four snapshots maximum: main + Fleet, main + IDEA, feature-branch + Fleet, and feature-branch + IDEA.
Note that storing warm-up snapshots is included in disk storage billing. Learn more about billing.
To view warm-up snapshots available in a project
In the sidebar, select Dev Environments.
Switch to the Warm-up Snapshots tab.
To view warm-up snapshots available in a project
In the sidebar, select Dev Environments.
Switch to the Warm-up Snapshots tab.
To delete a warm-up snapshot
In the sidebar, select Dev Environments.
Switch to the Warm-up Snapshots tab.
Find the snapshot and click the
Delete button.
To delete a warm-up snapshot
In the sidebar, select Dev Environments.
Switch to the Warm-up Snapshots tab.
Find the snapshot and click the
Delete button.
Set environment variables
To define environment variables in a dev environment container, use the components.container.env parameter.
When creating a new environment, you can view the added variables under Environment variables.
After you push the updated devfile to the project repository, the specified environment variables will be available only in the newly created dev environments.
Provide project parameters and secrets to a dev environment
You can provide a dev environment with parameters and secrets that are common for the entire project, for example, URLs, file paths, common auth tokens, and so on.
To reference the required project parameters and secrets, use the project's devfile. A dev environment will take the values from the project's storage of secrets and parameters.
On the project sidebar menu, choose Settings, then Secrets and Parameters.
Click Create and choose Secret or Parameter.
Specify
Key: a parameter name. You will use this name to reference this parameter in the devfile.
Value: a parameter value.
Limitations:
Secrets and parameters exist only in the scope of a particular project. So, if you create a secret or a parameter in one project, you cannot use them in other projects.
Keys of secrets and parameters must be unique within a project. A secret and a parameter with the same key are also not allowed.
A key must be no longer than 128 characters and can only contain alphanumeric characters (
[a-z],[A-Z],[0-9]), dashes (-), or underscores (_).Keys are case-insensitive.
Max secret's or parameter's value size is 30KB.
To reference the created project secrets and parameters in a devfile, assign them to environment variables. The parameter or secret name (key) must be preceded with the
project:prefix. For example:# suppose we created a project parameter 'service-url' # and a project secret 'auth-token' schemaVersion: 2.2.0 attributes: space: instanceType: large editor: type: Idea components: - name: dev-container container: env: - name: URL value: '{{ project:service-url }}' - name: TOKEN value: '{{ project:auth-token }}'
Provide personal parameters and secrets to a dev environment
You can require users to provide personal values for particular dev environment parameters and secrets. For example, these could be user credentials for downloading project binary dependencies. The required parameters and secrets are available on a target dev environment as environment variables.
To define the required environment variables (i.e., parameters and secrets), use the project's devfile. When creating a dev environment, a user will be asked to provide variable values. The values must be taken from the personal user storage of secrets and parameters.
To define the required environment variables
Open the devfile in the project repository. If it doesn't exist, create a new one, for example,
.space/devfile.yaml.Specify the required environment variables. For example, we require an environment variable
DB_USERNAME(the value is expected to be a plain parameter) and a variableDB_TOKEN(the value is expected to be a secret):schemaVersion: 2.2.0 attributes: space: instanceType: large editor: type: Idea requiredParameters: - name: DB_USERNAME description: 'Database username' requiredSecrets: - name: DB_TOKEN description: 'Database access token'Commit and push the changes.
After this, when creating a dev environment, a project developer will be required to provide values for the defined secrets and parameters (this has to be done only for the first created environment; all subsequent environments will have these settings pre-defined).
To assign personal secrets and parameters to the required environment variables
On the Personal navigation sidebar, click Dev Environments, then click Environment Variables.
Create a parameter or a secret by clicking New parameter or New secret.
Specify
Key: a parameter/secret name.
Value: a parameter/secret value.
When creating a new dev environment, in the New Dev Environment window, under Environment variables, assign environment variables to the corresponding parameters and secrets.
Note that the specified environment variables are set only in newly created dev environments. There will be no such variables in the existing dev environments.
Configure JVM options for IntelliJ-based IDEs
In some cases, you might need to change the configuration of Java Virtual Machine (JVM) your IntelliJ-based IDE runs on. For example, increase the maximum memory heap size allocated for the IDE.
To specify the required JVM options, use the vmoptions list. For example, to set the initial and max memory heap size allocated for the IDE:
After you push the updated devfile to the project repository, the specified JVM options will be applied only to newly created dev environments.
Specify the project root directory
After you start a dev environment, an IDE opens a project root directory. By default, the project root is the repository root. You can specify an alternative project root location (relative to the repository root) using the projectRoot parameter. This might be helpful for mono-repositories which include multiple projects.
Also note that all path parameters in a devfile (e.g., components[*].image.dockerfile.uri and components[*].image.dockerfile.buildContext) are specified relative to the project root.