Using the dev container to debug (not recommended)

Before using the dev container

It is always preferable to debug in a local development environment rather than inside the container. Containers are designed primarily for end-users and may not have all the necessary debugging tools available.

Using the dev container

To facilitate development and testing, we have included a step in our GitHub Action workflow called build-dev. This step creates a container in the repository tagged as the dev container, which can be pulled from either the ghcr or Docker Hub registries using the following commands:

docker pull ghcr.io/mspass-team/mspass:dev

docker pull mspass/mspass:dev

Unlike the standard container build step, this step is enabled in all branches. As a result, any commits to any branch in this repository will create its own dev container and overwrite the latest dev container. Therefore, to ensure that you pull the desired dev container, double-check and make sure the latest one has been created by the corresponding commit. Alternatively, you can push a new commit, wait for the workflow that builds the dev container to complete, and then immediately pull the dev container to ensure that you obtain the version you want.

Using the sha256 manifest to locate a specific version

Alternatively, you can use the sha256 value of the manifest, which serves as a unique identifier for a container image, to locate a specific version of the dev container. To do so, follow these steps:

1. Go to the "Actions" tab of the repository.
2. Filter the "Docker" workflows from the left panel.
3. Click into the log of the workflow of interest.
4. Click the "build-dev" workflow to see the logs.
5. Expand the "Build and push dev image" section and search for the manifest towards the end of the log. It should appear as follows:

...
#34 exporting to image
#34 pushing layers 8.4s done
#34 pushing manifest for docker.io/***/***:dev@sha256:ce91a942bf8715ac3932fe18061df66286123eb3cb9542c89c8d7eb49e93186f
#34 pushing manifest for docker.io/***/***:dev@sha256:ce91a942bf8715ac3932fe18061df66286123eb3cb9542c89c8d7eb49e93186f 0.8s done
...
#34 exporting to image
#34 pushing layers 4.8s done
#34 pushing manifest for ghcr.io/***-team/***:dev@sha256:ce91a942bf8715ac3932fe18061df66286123eb3cb9542c89c8d7eb49e93186f
#34 pushing manifest for ghcr.io/***-team/***:dev@sha256:ce91a942bf8715ac3932fe18061df66286123eb3cb9542c89c8d7eb49e93186f 2.6s done
...

In this example, the manifest of the dev container being built is ce91a942bf8715ac3932fe18061df66286123eb3cb9542c89c8d7eb49e93186f. You can pull this specific version using the following commands:

docker pull ghcr.io/mspass-team/mspass:dev@sha256:ce91a942bf8715ac3932fe18061df66286123eb3cb9542c89c8d7eb49e93186f

or

docker pull mspass/mspass:dev@sha256:ce91a942bf8715ac3932fe18061df66286123eb3cb9542c89c8d7eb49e93186f

Note that if you pull the container with the manifest, it is necessary to reference that same manifest in any of your subsequent docker commands that uses the dev container.