Devfile

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. Space supports only a feature subset of the 2.2.0 specification (the supported features are fully covered by the current Space documentation – if a feature is not mentioned in this documentation, it's not supported).

Devfile location

my-project // project root
├─── .space
│   ├─── frontend.devfile.yaml  // user devfile
│   ├─── backend.devfile.yaml   // user devfile
│   └─── ...                    // *.devfile.yaml files
│
...

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.

Create a devfile

You should create a devfile manually in the .space directory of your project. If you create or edit the devfile in the Space UI, you can use the built-in devfile snippets.

Auto-generated devfiles

A project owner can enable automatic generation of devfiles for the project. If a user doesn't specify a particular devfile when creating a new dev environment, Space will generate a devfile automatically based on the settings provided in the creation dialog. The generated devfile will be stored in .space/generated.devfile.yaml (if the file already exists, it'll be rewritten). After the dev environment is created, the user can commit and push this file to the project repository.

To enable devfile auto-generation

Open a project.
In the sidebar, choose Dev Environments.
Click Settings and select Auto-generate a devfile on start if an existing file is not specified.

Devfile example

schemaVersion: 2.2.0
metadata:
  name: 'My custom dev env configuration'
attributes:
  space:
    # regular, large, xlarge
    instanceType: large
    # a default IDE for the project
    editor:
      # (Required) IDE type: Idea, WebStorm, PyCharm,
      # RubyMine, CLion, Fleet, GoLand, PhpStorm
      type: Idea
      version: '2022.1'
      # Space uses JetBrains Toolbox App to install IDEs to a dev environment.
      # updateChannel defines IDE version release stage: Release, EAP
      updateChannel: EAP
      # JVM configuration (appends to the default .vmoptions file)
      vmoptions:
      - '-Xms2048m'
      - '-Xmx4096m'
    # a warm-up snapshot
    warmup:
      # create a snapshot every Sunday (only for main branch)
      startOn:
      - type: schedule
        cron: '0 0 0 ? * SUN *'
      # run additional warmup script (IDE indexes will be built anyway)
      script:
        ./scripts/warmup.sh
    # Parameters and secretes required by a dev environment
    # e.g., credentials to an external service
    requiredParameters:
    # (Required) the name of the environment variable
    # that will be available in the dev environment
    - name: USERNAME
      description: 'Space username'
    requiredSecrets:
    - name: PASSWORD
      description: 'Space permanent token'
components:
- name: dev-container
  # Dev environment container config
  container:
    # use image from a Space Packages registry
    image: mycompany.registry.jetbrains.space/p/myprj/container/my-dev-image:27
    # environment variables
    env:
      - name: API_URL
        value: 'https://my-site/http_api'
      - name: PATH_IMG
        value: './img/'

Last modified: 04 March 2024