VS Code Remote Usage with Docker

Last update: 20 Oct 2023 [History] [Edit]

Use Case

If you have convenient access to a laptop/desktop running some reasonably modern Linux distribution (which is not CentOS 7), on which CVMFS and Docker is available, this method may be ideal for you to develop ATLAS offline software with.

While technically macOS can also be used to run VS Code in this way, the performance of it at the time of writing (5th December 2019) is not really appropriate for “real” work. (It is very slow.)


You will need all of the following to use VS Code with Docker for developing ATLAS offline/trigger code:

  • A version of Linux for which VS Code is available;
  • CVMFS correctly set up to be able to mount all of the following repositories on the host:
    • /cvmfs/atlas.cern.ch
    • /cvmfs/atlas-nightlies.cern.ch
    • /cvmfs/atlas-condb.cern.ch
    • /cvmfs/sft.cern.ch
  • Docker set up correctly, such that the user running VS Code is allowed to download and use images;
  • You need to install ms-vscode-remote.vscode-remote-extensionpack to use “remote” code development.

Note that the setup that we have for the athena repository will auto-install VS Code extensions that are known to work well with our Docker image. So on first order you do not need to worry about that part.


In a terminal on the host, clone the athena repository (most likely your fork of the repository) into a convenient location. Just as with all other modes, you will need to have a full checkout of the repository. The layout of your work area will be the same in this mode as in all the others. You should check out the athena repository in a place that has enough room for the accompanying build/ directory to go beside it.

After the repository is checked out, create an empty build/ directory right beside it. (If you don’t, Docker will do it for you, and it will do so by default by making root the owner of the directory.)

Press F1, and choose “Remote-Containers: Open Folder in Container…”. In the upcoming file selector select the athena/ directory that you just checked out. This will start setting up the Docker container, which may take a couple of minutes when you’re doing this for the first time. (Or after you cleared the images off of your machine.) If all goes well, you should end up with a view like the following:

Notice the error message in the lower-right. That tells us that before we can start editing C++ source files with IntelliSense support, we first need to set up the partial build of the packages that we want to work on.

To do this, use the terminal that is automatically opened when you open the athena repository in a container. In the terminal go to the ../build directory (relative to where the terminal starts from), which corresponds to the build/ directory that you have set up on your local disk. In this directory set up the ATLAS release/nightly that you want to build against. Note that the setupATLAS command is available out of the box in this terminal. So a possible setup would be:

Now comes the tricky part… To set up the partial build that you need, you have to set up a package filter file that you will be able to give to the cmake command. One option is of course to just edit the Projects/WorkDir/package_filters_example.txt file in place, inside the VS Code editor. But this would modify the content of the local checkout of the repository for no good reason. So a better approach is to create a filter file inside the build/ directory. (Most easily by copying the example, and adjusting it.) It needs to be inside the build/ directory, since that’s one of the only places in the Docker image where you have write access by default.

What makes this part extra awkward is that you need to edit that text file on your host OS. As the Docker image started by VS Code is lacking any command line text editor, and VS Code itself is not providing access to the build/ directory for text editing.

Once you created an appropriate package filter, just set up a partial build as usual, like:

cmake -DATLAS_PACKAGE_FILTER_FILE=package_filters.txt ../athena/Projects/WorkDir/

Once this is done, you are ready to start editing files from the packages that you have set up for a partial build, and you can also build them in the usual way, by executing make in the terminal.