Internals of the EVerest Development Container

This document explains the internal working of the EVerest development container (devcontainer) for different setup variants and how things are connected.

For a more hands-on explanation, consider reading:

The Docker Compose Project Name

The Docker Compose project name determines how containers are named and grouped. By default, it uses the current folder name with _devcontainer suffix (consistent with VSC behavior), but can be customized.

Set the environment variable DOCKER_COMPOSE_PROJECT_NAME to your desired project name before building/starting the devcontainer.

For example:

DOCKER_COMPOSE_PROJECT_NAME=my-project ./applications/devrd/devrd Start

This will name the containers with the pattern:

{project_name}-{service}-1, where

  • {project_name} is the value of DOCKER_COMPOSE_PROJECT_NAME

  • {service} is the service name defined in the docker-compose files

  • 1 is the instance number (default is 1)

Environment Variables

You can generate an .env file with auto-detected values using this command:

./applications/devrd/devrd env

This will create a .devcontainer/.env file with the following content:

# Auto-generated by setup script
ORGANIZATION_ARG=EVerest
REPOSITORY_HOST=github.com
REPOSITORY_USER=git
COMMIT_HASH=<..>
EVEREST_TOOL_BRANCH=main
UID=<..>
GID=<..>
HOST_WORKSPACE_FOLDER=<..>

These variables are automatically mapped in the container to the following environment variables:

  • ORGANIZATION_ARG: Maps to EVEREST_DEV_TOOL_DEFAULT_GIT_ORGANIZATION

  • REPOSITORY_HOST: Maps to EVEREST_DEV_TOOL_DEFAULT_GIT_HOST

  • REPOSITORY_USER: Maps to EVEREST_DEV_TOOL_DEFAULT_GIT_SSH_USER

  • EVEREST_TOOL_BRANCH: Maps to EVEREST_TOOL_BRANCH

  • HOST_WORKSPACE_FOLDER: The directory mapped to /workspace inside the container

Use this mechanism if you have a different organization or git host or user. This is useful if you have forked and you are hosting your development outside github.

Workspace Folder Mapping

The /workspace directory inside the container can be mapped to any folder on your host system. The workspace folder is determined in the following priority order:

  1. Command line option: -w or --workspace flag

  2. Environment variable: HOST_WORKSPACE_FOLDER environment variable

  3. `.env` file: HOST_WORKSPACE_FOLDER value in .devcontainer/.env

  4. Current directory: Falls back to the current working directory

The .devcontainer directory (containing .env and Docker Compose files) is always located relative to where the devrd script is installed. This allows you to:

  • Run devrd from any directory in your workspace

  • Use a single devrd installation to manage multiple workspaces by changing HOST_WORKSPACE_FOLDER in the .env file

One can set workspace mapping via command line:

./applications/devrd/devrd env -w /path/to/workspace

Or edit .devcontainer/.env directly and set HOST_WORKSPACE_FOLDER Then run from anywhere:

cd /path/to/workspace/subfolder
../applications/devrd/devrd start  # Works correctly, uses workspace from .env file

Troubleshooting

See the separate troubleshooting section for help on devcontainer-specific issues.

Authors: Florian Mihut, Andreas Heinrich