A Visual Debugger for DVM-DOS-TEM in Docker Container on GCP Instance

[Benjamin-Maglio]

Approximately 6 months ago @rarutter added /.vscode to the repository in commit 927978c which contained a launch.json file, enabling the use of a visual debugger in Visual Studio Code when running the model from within a Docker Container. This provides a powerful utility for debugging and development of DVM-DOS-TEM. However, as many users work primarily on cloud-based VMs, there was an extra layer of complexity to use this feature, requiring a remote-ssh into the instance, and then mounting to a running container, which we think we have solved.

General vscode setup instructions for host machine to docker container (host->docker):

1. Install Visual Studio Code on host
2. Install extensions in vscode (Docker, Dev Containers, C/C++)
3. With docker containers running, View->Command Pallete (or Ctrl-Shift-P)
4. Run Remote-Containers:Attach to Running Container - this will list all running containers
5. Select appropriate container (normally dvmdostem-dev) in remote explorer tab on the left. Check lower left of screen, this should state Container dvmdostem-dev etc
6. Now, you must install C/C++ extension again inside docker container
7. Once installed, access the run and debug panel on the left (or Ctrl-Shift-D) or use Run->Start Debugging (note, you may need to make changes to the launch.json file to set run stage options.
   More information on debugging using this platform can be found here.

Subsequently, setup for vscode for host->cloud-instance as follows:

1. Install extensions (Remote - SSH, Remote Explorer) in vscode on host
2. View->Command Pallete (or Ctrl-Shift-P) and enter "Remote Explorer: focus on remote view"
3. Select "add new ssh host"
4. Enter SSH command for your cloud-instance (for GCP see this)
5. This should populate remotes with a list of VMs associated with your account
6. Make sure your remote cloud-instance is running, and select this (you may need to reconfigure your .ssh config file, see this)
7. From here you should be in your instance and be able access all files on your cloud-instance

Finally, to setup the visual debugger for host->cloud-instance->docker:

1. Once you've accessed your cloud-instance using the previous steps, you will need to make some accessibility changes on the cloud-instance, you can do this in the terminal of vscode or from whichever method (browser, ssh) you normally access you cloud-instance
2. Make sure docker containers on cloud-instance are running
3. You must first run sudo groupadd docker then sudo usermod -aG docker $USER on you cloud-instance (but not inside docker) to allow for commands to be made without being a super user (use newgrp docker or log out/in to activate changes)
4. Now, from vscode you need to reinstall extensions (Docker, Dev Containers is not needed as this should be enabled globally, maybe C/C++ is needed though) on cloud-instance remote
5. Access View->Command Pallete (or Ctrl-Shift-P) and enter Dev Containers:Attach to running container
6. At this point you should be working from vscode on host, using remote-ssh to access cloud-instance and attached to docker container on the cloud-instance
7. Finally, you will need to reinstall extension (C/C++) in docker on cloud-instance and you should be able to begin debugging as in the intial set of instructions.

Note: due to the multiple ssh layers connection is slow, you may need to change the refresh rate to something longer than the default with docker.explorerRefreshInterval following this.