JetBrains Space Help

Prepare a Dev Environment for a Project

Preparing a dev environment is an optional step. If you skip it, Space will use a default dev environment: the environment based on the default container image and without project warm-up data. Nevertheless, to provide the best possible experience, a dev environment must be configured for your project. The configuration consists of two steps:

  1. Configure a dev environment container image: choose a base image, add the required tooling and runtimes, set env variables, and so on. You should configure your custom image with a Dockerfile file located in the ./.fleet or ./.jb-gateway directories depending on your IDE.

    Default image: If you don't configure a custom Docker image for a dev environment, Space will use the default image. The default image is based on Ubuntu OS and includes Git, curl, Docker, Docker Compose, and Open JDK.

  2. Warm up the environment: create project indexes, download project dependencies, build caches, and so on. This is done with the help of an Automation job configured in the ./.space.kts file. Space can run the warm-up Automation job by schedule, on each commit, or by other triggers.

So, the dev environment is configured with only two files both located in VCS along with the project source code. This means that typically you have to configure the dev environment only once for a project. This also lets you experiment with dev environment configuration: just create a separate branch and change the config files there.

Container image vs warm-up job

In some cases, you may face a dilemma where to put a certain preparation step: to a container image or to a warm-up job. For example, your project requires an SDK. To get the SDK, you run the script: curl - o sdk.zip $SDK_URL && unzip sdk.zip. Where do you put this line: to the Dockerfile or to the warm-up job in .space.kts?

Our recommendation is to use the Dockerfile only to configure the environment. All binary dependencies should go to a warm-up job. So, in the example above, the best solution would be to get the SDK in a warm-up job.

Step 1. Configuring an image for the dev environment

A dev environment is just a Docker container, so you can install all the required tooling and runtimes using a Dockerfile. If you don't create your custom Dockerfile, Space will use the default dev environment image.

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 an IDE).

  • The container must run as root (no non-root users in Dockerfile).

To configure a dev environment image

  1. Open the project source code and create a Dockerfile file in:

    • the ./.fleet directory for JetBrains Fleet

    • the ./.jb-gateway directory for JetBrains Gateway

    If the directory doesn't exist, create it.

  2. Use the Dockerfile to 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-amd64

Step 2. Warming 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 resolves project dependencies, builds indexes, and does other background activities. You can put all these routines into a Space Automation job and run this job on schedule, on every commit, or using other triggers. A result of the warm-up job is a disk snapshot (or warm-up snapshot) that is then mounted to a dev environment.

When running the warm-up job, Automation:

  1. Builds project indexes: Automation does this by default, no configuration from your side is required.

  2. (Optional) Runs your custom .sh script that contains other warm-up activities.

To run the warm-up job, Automation uses a container image based on your custom Dockerfile created in Step 1. If the Dockerfile is not found, Automation will use the default dev environment image.

Creating warm-up snapshots

To create a warm-up snapshot

  1. Open the project repository.

  2. (Optional) Add a .sh file, for example, ./dev-env-warmup.sh. The file can be located anywhere in the project.

    Open dev-env-warmup.sh and add any warm-up activities that are required in addition to building project indexes. For example, for a Java project that uses Gradle you may want to download references with

    ./gradlew assemble

  3. Open the .space.kts Automation script file. If the file doesn't exist, create it in the project root.

  4. Add an Automation job that runs the warm-up. For example, the simplest warm-up job that only builds project indexes for your IDE:

    // this job will run on every git push job("My project warmup data for Fleet") { // ide is an IDE you want Space to build indexes for: // Ide.Fleet for JetBrains Fleet // Ide.IJGateway for IntelliJ-based IDEs via JetBrains Gateway warmup(ide = Ide.Fleet) }

    Or a more complex warm-up job that runs your custom .sh script:

    job("My project warmup data for Gateway") { // optional startOn { // run on schedule every day at 5AM schedule { cron("0 5 * * *") } // run on every commit... gitPush { // ...but only to the main branch branchFilter { +"refs/heads/main" } } } warmup(ide = Ide.IJGateway) { // path to the warm-up script scriptLocation = "./dev-env-warmup.sh" } // optional git { // fetch the entire commit history depth = UNLIMITED_DEPTH // fetch all branches refSpec = "refs/*:refs/*" } }

  5. Commit the changes to the repository.

  6. Make sure the job is run and completed successfully. You can check the job state on the project's Job page.

  7. After the job completes successfully, it'll be possible to select the created warm-up snapshot in the New Dev Environment window.

  8. Make sure the job is run regularly: The fresher the index data is, the faster a dev environment will be ready for work. Note that if the project indexes are outdated, an IDE won't rebuild the entire index data from scratch, it will only create the missing index data.

To create a number of different warm-up snapshots

  1. Some projects may require different warm-up data. For example, a project may include a server, client, mobile app, and other parts. All the parts are developed by different teams with different tool sets. Another use case when you may need a number of different warm-up snapshots is building indexes for different IDEs.

    To prepare a number of different warm-up snapshots, create the corresponding number of jobs, each with a warmup block inside. For example:

    job("Server warmup data") { startOn { schedule { cron("0 5 * * *") } } warmup(ide = Ide.Fleet) { scriptLocation = "./dev-env-server-warmup.sh" } } job("Mobile warmup data") { startOn { schedule { cron("0 8 * * *") } } warmup(ide = Ide.Fleet) { scriptLocation = "./dev-env-mobile-warmup.sh" } }

  2. When creating a dev environment, you can choose a particular warm-up snapshot.

Storing warm-up snapshots

Space stores only the latest warm-up snapshot for each combination of an IDE and a Git branch. For example, a project has two branches: main and feature-branch. Suppose some developers use JetBrains Fleet and some use IDEA with JetBrains Gateway. There can be four snapshots maximum: main + Fleet, main + Gateway, feature-branch + Fleet, and feature-branch + Gateway.

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

  1. Open the project.

  2. In the sidebar, choose Dev Environments.

  3. Click Warm-up Snapshots.

To delete a warm-up snapshot

  1. Open the project.

  2. In the sidebar, choose Dev Environments.

  3. Click Warm-up Snapshots.

  4. Find the snapshot and click the Delete dev environment Delete button.

Last modified: 01 December 2021
Dev Environments Develop in a Dev Environment