:title: Managed by VSCode

###################################################
Setup Variant: Service Containers Managed by VSCode
###################################################

This variant makes use of the VSCode Dev Containers extension [#vscode_devcontainter]_
.
This will allow to run commands in the VSCode built-in terminal.
It will manage the service containers by starting them together with
the `devcontainer` itself. Dedicated control of individual services
is not possible with this variant.

******************************
What to expect from this setup
******************************

By following the steps in this tutorial you will setup a development
environment for EVerest using a development container (devcontainer).
VSCode will automatically build the container. After this all development
happens inside the container.

The contents of the EVerest repo are mapped inside the container
in the directory ``/workspace``
You can exit VSCode at any time, re-running it will cause VSCode to ask you
again to reopen in container.

Opening the EVerest repository in the VSCode devcontainer will
automatically start all of the provided service containers.

*************
Prerequisites
*************

To install the prerequisites, please check your operating system or distribution online documentation:

- Docker installed [#docker]_
- Docker compose installed version V2 (not working with V1) [#docker_compose]_
- VS Code with Dev Containers extension installed [#vscode_devcontainter]_

**************
Required Steps
**************

1. **Clone the EVerest repository**

   If you have not done this yet, clone the EVerest repository
   from GitHub to your local machine:

   .. code-block:: bash

       git clone https://github.com/EVerest/EVerest.git path/to/EVerest

   Where ``path/to/EVerest`` is the path where you want to
   clone the repository to.

2. **Open in VSCode**

   Then open this repository in VSCode:

   .. code-block:: bash

       code path/to/EVerest
   
   Choose **Reopen in container** when prompted by VSCode.

Now VSCode will build the devcontainer.
This can take some time depending on your machine and internet connection.
After this you can use the built-in terminal in VSCode to run commands
inside the devcontainer as for example to build EVerest.

*************
Example Usage
*************

You can now use VSCode's terminal to issue commands inside the devcontainer, e.g. for building:

.. code-block:: bash

    docker@16898a21b4f1:/workspace$ mkdir build
    docker@16898a21b4f1:/workspace$ cd build
    docker@16898a21b4f1:/workspace$ cmake ..
    docker@16898a21b4f1:/workspace$ cmake --build . --parallel 8

This will readily build EVerest regardless of your host system setup.

****************************************
Tips for VSCode Dev Containers Extension
****************************************

When the repository is opened in VSCode you can enter the devcontainer at
any time by running the command **Dev Containers: Reopen in Container** from the
command palette (F1).
You can also stop the devcontainer by running the command **Dev Containers: Reopen Folder Locally**.

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

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

----

**Authors:** Florian Mihut, Andreas Heinrich

.. [#docker] `<https://docs.docker.com/engine/install/>`_
.. [#docker_compose] `<https://docs.docker.com/compose/install>`_
.. [#vscode_devcontainter] `<https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers>`_
