Using devcontainers in Linux

Table of contents

Overview

If setting up a shared Linux server this document assumes that an experienced devops person is performing these tasks.

The GCubed system uses Dev Containers (an open-source standard for definition of Docker environments) as a platform and consists of server and client components.

The server runs the Docker Engine and the VS Code Server which together host the GCubed docker container and provide access to that container when it is running. It can run on a local machine (Linux, macOS, Windows WSL), on a remote self-hosted linux instance, or a cloud linux instance.

The GCubed container holds all files, executables, and configuration required to run the GCubed framework; and it is in this context that the GCubed code executes.

The client runs the VS Code front-end which acts as the User Interface and connects to the server. This is usually run on a local machine (Linux, macOS, or Windows), or in a cloud instance via web browser (ie: in a GitHub codespace).

The client communicates with the server to manage the container lifecycle, edit GCubed files, manage interactions with the git repository, and provide terminal sessions to execute GCubed code.

Client and server processes can reside on the same or different machines. The client part uses a graphical user interface (ie desktop environments such as KDE, GNOME, XFCE, LXDE, MATE, etc) to present the VS Code front-end to the user, whilst the server part can run on a machine which has a desktop environment or simply run ‘headless’ with just a command-line interface. Depending on how client and server are set up they can also use various methods to communicate with each other - IPC, tunnels, sockets, SSH, etc.

The most common configurations in this context are where either both parts run on a single user’s (unshared) local machine or where the backend runs on a shared server machine (be it either on-prem or cloud) and is used by multiple users. In this case the front-end can run on any platform (Linux, macOS, or Windows) and will use SSH to communicate with the server.

Server installation and configuration

Each GCubed user in your organisation must have a unique user account on the local Linux server where they will store and work with their own private copy of the GCubed Git repository.

Your organisation may have fewer, or even only one, user account(s) in the MSG GitHub organisation. It is acceptable for local linux server users to share one or more set of MSG user credentials.

Different Docker configurations are recommended depending on whether the server is running on a private single-user machine, or a shared server. A private machine can run either the default Docker Engine installation, Docker Desktop, or Rootless Docker, whereas it is strongly recommended to run Rootless on a shared server as the default Engine installation can both end up granting root-level privileges to the user and making the docker container visible and available to other users on the same machine. See here for more information.

Create user account(s)

If necessary, create one or more local Linux user accounts on the server.

Install and configure Docker

You can elect to install just the Docker Engine or Docker Desktop (which includes Engine) if the server is running a GUI desktop environment and you are running on a private machine.

For a shared server we strongly recommend installing Docker Engine in Rootless mode.

The official guide for installing Docker:

  • Engine is here and post-installation steps are here
  • Rootless is here
  • Desktop is here.

If using Rootless Docker follow the instructions for ensuring that Docker starts automatically after a machine restart, and ensure that you both specify the socket path using $DOCKER_HOST (add this environment variable to the user’s .profile or .bashrc file) and specify the CLI context using docker context (this only needs to be done once).

Ensure that the socket path is unique and only visible to that linux user.

If using Docker Desktop you do not need to create a Docker account to use the application, however the application must be running to use devcontainers. It can be configured to start on boot if you wish.

In order to avoid a substantial performance impact when creating or rebuilding containers, in Docker Desktop go to Settings (the cog wheel in top right corner) / General and ensure that SBOM indexing and enable background SBOM indexing are both turned OFF. You may need to scroll down to find those settings. Also, ensure that under Settings / Features in Development all Beta and Experimental features are turned OFF. These settings can otherwise adversely impact performance on computers with constrained capacity.

Install git

See instructions here

Per local server user configure the git user.name and user.email parameters to reflect that user’s details.

Configure SSH keys

Optional, though recommended, create SSH keys for each user account that will be accessing the McKibbin Software Group Bank of Canada GitHub repository. Share the public key with the GitHub user(s) account (instructions here) and the private key with each local Linux user (ensure that the private key file has a unique and easily recognised name, and that permissions to this file are restricted to only the local linux user account).

It is recommended to create/update the <user home directory>/.ssh/config file with a reference to the private key:

Host gcubed.github.com
  User git
  HostName  github.com
  IdentityFile ~/.ssh/<filename of private keyfile>
  AddKeysToAgent yes

This will then allow git to operate transparently with GitHub using the SSH method, for example:

git clone gcubed.github.com:McKibbin-Software-Group/<repository-name>

Clone the base GCubed repository

For each user, clone the base GCubed repository into a private location (usually a subdirectory in the user’s home directory).

Client installation and configuration

Install VS Code on the user’s local machine

Several Linux packages are supported by Visual Studio. Download and install the appropriate package VS Code for Linux using the package manager associated with your version of Linux.

Once VS Code is installed, try starting VS Code in a terminal session:

code .

The VS Code version can be checked with:

code --version

Install VS Code extensions

Once VS Code is running successfully you then need to install the VS Code Remote Development extension pack available here.

Configure SSH if using Remote/Shared Server

Similar to configuring SSH keys for the server to connect to GitHub, it is strongly recommended to set up SSH keys for the client to connect to the shared Linux server as this will make working with the server significantly easier. Remember to add the server definition to the SSH config file.

Running devcontainers on Linux

Single User Installation On Local Machine

  1. Open a Shell in Linux
  2. Clone a devcontainer repository to your local drive. For instance:
git clone https://github.com/McKibbin-Software-Group/gcubed-2R.git
  1. Change to the repository folder
cd gcubed-2R
  1. Start VS Code
code .

Requires the ‘dot’ / ‘full stop’ after code - this instructs VS Code to open the current folder.

All going well, VS Code should open and display all the files & directories in that folder.

The devcontainer has not started yet. You can just edit the files in that clone of the repo, but none of the development environment is running and you can’t access the G-Cubed tools. VS Code may at this point offer to reopen as a devcontainer (select that) or you may need to manually open the container.

You can manually start the devcontainer by pressing COMMAND+SHIFT+P and typing reopen. You should see a search window open and the option Dev Containers: Reopen in Container should appear at or near the top of the list. Select that option.

You can finish the session and shut down the container by simply closing the VS Code window. You can restart your session by re-opening a Terminal, changing to the repository folder, and starting VS Code code .

You may also need to reopen the devcontainer from within VS Code.

By default VS Code remembers where you left off and will restart in the same location. Simply starting VS Code from within Linux should automatically restart the devcontainer and open the previous editor windows.

Troubleshooting

  • Permissions Issues: Ensure your user is part of the docker group to avoid permission issues with Docker.
sudo usermod -aG docker $USER
newgrp docker
  • Container Build Issues: Check the output of the build process in the VS Code terminal for any errors.

Using A Shared Server

  1. Start VS Code on your local machine
  2. CTRLSHIFTP or CMDSHIFTP to bring up the Command Palette
  3. Search for and select Remote-SSH: Connect Current Window To Host...
  4. If the shared server SSH certificates have been properly configured then the server name will be shown and connection will be made immediately on selection
    • If not, then select + Add New SSH Host enter the hostname, and follow prompts to enter credentials
  5. Once connected click Open Folder and navigate to the directory where the base MSG repository was cloned into
  6. Once the directory opens, bring up the Command Palette again and select Dev Containers: Reopen In Container
  7. The system should then proceed to automatically install the remainder of the prerequisites and you should be able to commence using the GCubed platform