##############################################
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:

- :doc:`Tutorial: Setup the EVerest Development Container </tutorials/setup-devcontainer/index>`
- :doc:`How-to Guide: How to use a development container for EVerest development and sil testing </how-to-guides/devcontainer-usage/index>`

*******************************
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:

.. code-block:: bash

    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:

.. code-block:: bash

    ./applications/devrd/devrd env

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

.. code-block:: bash

    # 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:

.. code-block:: bash

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

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

.. code-block:: bash

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

***************
Troubleshooting
***************

See the :doc:`separate troubleshooting section </tutorials/setup-devcontainer/troubleshooting>` for help
on devcontainer-specific issues.

----

**Authors:** Florian Mihut, Andreas Heinrich