SNID-Docker

This short Docker file uses a containerized approach to easily enable running the SuperNova IDentification code (Blondin & Tonry, 2007, Tonry & Davis, 1979) on any platform. The requisite PGPLOT library including the X-Windows interface is automatically downloaded and installed inside a Linux container. SNID is configured and built on top of PGPLOT. The container hosts an X11 client which the user can easily connect to via a local X11 server on their desktop. All of this is accomplished by executing a single script, run_snid.sh, which automatically detects the system architecture and launches Docker and the X11 server.

References:

"Determining the Type, Redshift, and Age of a Supernova Spectrum" Blondin, S. & Tonry, J. L. 2007. ApJ, 666, 1024

"A survey of galaxy redshifts. I - Data reduction techniques" Tonry, J. L. & Davis, M. 1979. AJ, 84, 1511

The current implementation has been verified on macOS Intel and Silicon and Windows Home x86-64, but has not yet been tested on Windows Pro or Linux. If you find this project useful, you can cite the Zenodo DOI below.

Initial Docker implementation by Robert Fisher, with contributions from Robert D. Stein and Krut Patel. Continuous integration test suite developed with Claude.

Running Instructions

Prerequisites

Required Software

1. Docker Desktop

   • Download and install Docker.

2. SNID and Template Library

   • Download the gzipped tarballs snid-5.0.tar.gz and templates-2.0.tgz from Stéphane Blondin's website [https://people.lam.fr/blondin.stephane/software/snid/]. Store these in the same local working directory where you have cloned this github repo.

3. An X11 Client

   • MacOS: Download and install XQuartz. You must completely restart your computer after installing XQuartz before proceeding.
   • Windows: Download and install either XMing, Cygwin/X, or VcXsrv. Note Cygwin/X is part of the larger Cygwin project. You will also need a command line terminal -- either WSL, Git Bash, or Cygwin. Also NB: VcVsrv generates an odd color palate for SNID's graphics, but XMing seems to work fine.
   • Linux: X11 is installed as part of most Linux distros. You can verify by simply typing startx in a terminal. If X11 is not installed, you can install it using the relevant package manager on your system. For example:
     • sudo apt install xorg(Debian/Ubuntu)
     • sudo dnf install xorg-x11-server-Xorg xorg-x11-xinit xorg-x11-apps (Red Hat/CentOS/Fedora)
     • sudo pacman -S xorg-server xorg-apps xorg-xinit (Arch Linux)
     • sudo zypper install xorg-x11-server xorg-x11-xinit xterm (openSUSE)

4. This Github Repo

   • In the terminal, run git clone https://github.com/rtfisher/snid_docker.

Quick Start

All of the necessary commands to build and run the Docker container are automated in the bash script run_snid.sh. Simply open a terminal and cd to the directory storing this github repo and run:

./run_snid.sh

If all proceeds fine, you will see some output similar to

Configuring XQuartz to allow connections from Docker...
127.0.0.1 being added to access control list
Running Docker container 'snid-app'...
sniduser@4585bce060da:~/snid-5.0$

Following this, you will be dropped into the container. To verify SNID is functioning correctly, you can run

./snid examples/sn2003jo.dat 

An interactive window similar to the one above should display. If any issues arise, you should follow through the X11 configuration steps below.

You can optionally mount a local directory to the container to transfer files in and out. For example, to mount the directory /path/to/local/data to the container, run:

./run_snid.sh /path/to/local/data

The container will automatically copy the contents of the local directory to the container directory /home/sniduser/snid-5.0/localmount. You can then access these files from within the container.

X11 Configuration

The X11 configuration process is straightforward, but differs depending on your operating system and X11 implementation. Begin by launching the Docker application and your X11 server.

macOS: XQuartz Setup

1. Configure XQuartz
   • In the menu bar, click on XQuartz → Preferences.
   • Navigate to the Security tab.
   • Check the box labeled "Allow connections from network clients".
   • Apply the changes and restart XQuartz if prompted.

Windows

Option 1. XMing or Cygwin/X

• Launch XMing or Cygwin/X by executing the startx command in the WSL, Git Bash, or Cygwin terminal:

  startx

Option 2. VcXsrv

• Launch VcXsrv using the XLaunch wizard:
  • Display Settings:
    • Multiple windows
    • Display number: 0
  • Client Startup:
    • Start no client
  • Additional Settings:
    • Enable clipboard
    • Enable OpenGL (if required)
  • Finish to start the server.

Linux

1. Launch Docker
   • Ensure that Docker is installed and running on your Linux distribution.
   • Open your terminal and start Docker if it's not already running:

     sudo systemctl start docker

2. Share X11-unix path with Docker
   • Launch Docker.
   • Navigate to Settings → Resources → File sharing.
   • In the Virtual file shares section, add the following path: '/tmp/.X11-unix'.
   • Apply and restart the docker.

Configuring X11 and Verifying X11 Setup on macOS, Linux, WSL, Git Bash, or Cygwin terminal

1. Configure X11 Server Permissions

   • Allow loopback connections from Docker containers:

     xhost + 127.0.0.1

2. Verify the Setup

   • Run the following command to verify that permissions are correctly set:

     xhost

   • Expected Output:

     access control enabled, only authorized clients can connect
     127.0.0.1 being added to access control list
     

PGPLOT Font Issue

PGPLOT has a mechanism for displaying special characters (such as Å or ±) using escapes. Sometimes these do not display properly. This is a known issue -- if it arises, please see https://people.lam.fr/blondin.stephane/software/snid/faq.html#symbols for a simple and quick fix.

Manual Container Building and Launching

If you prefer to build and launch the container by hand, follow these steps:

1. Allow Docker to connect to X11 client via loopback:

   xhost + 127.0.0.1

2. Build the Docker container:

   docker build -t snid-app --progress=plain -f snid_dockerfile .

3. Launch the Docker container:

     docker run -it --rm \
         -e DISPLAY=$DISPLAY \
         -v /tmp/.X11-unix:/tmp/.X11-unix \
         snid-app

4. After use, revoke X server permissions:

   xhost - 127.0.0.1

General Notes on Docker

Credential Store Known Issue

If you encounter the error message:

error getting credentials - err: exec: "docker-credential-desktop": executable file not found in $PATH, out: 

This is a known issue which you can easily fix by editing ~/.docker/config.json, changing "credsStore" to "credStore":

{
    "credStore": "desktop"
}

Note: This change must be made each time Docker client restarts and overwrites the configuration file. Save the config file and restart Docker. This issue was present in older Docker versions and may appear on legacy systems (e.g., Intel architectures on older OS/X machines).

File Transfer

Option 1: Using Mounted Directory

The easiest way to transfer files from within the container back to the system is by using a directory mount. SNID-Docker mounts the container directory desktop to the directory snid on your system desktop. Any files you copy into the desktop folder in the container will automatically be copied to the snid folder and persist even after the Docker container is shut down. Similarly, any system files which are copied to snid on your system desktop will automatically appear within the mounted desktop folder in the container.

Option 2: Using Docker cp

To copy files from a subdirectory in the container to your system desktop, you could run:

docker cp snid-container:/home/sniduser/figures ~/Desktop/

Here the folder figures is being copied from the home directory of the container. Note: docker cp does not accept wildcards ("*"). Organize files in directories for easier transfer.

Cleanup and Management

Complete Docker Cleanup

To stop running containers and clean up disk space (WARNING: this removes all Docker containers):

docker ps -q | xargs -r docker stop && \
docker ps -aq | xargs -r docker rm && \
docker images -q | xargs -r docker rmi -f && \
docker volume ls -q | xargs -r docker volume rm && \
docker builder prune -a -f && \
docker system prune -a -f

Restarting Docker Daemon on OS/X

Very rarely you may need to restart the Docker daemon. On OS/X:

osascript -e 'quit app "Docker"'
open /Applications/Docker.app

Testing

This project includes a comprehensive test suite to ensure all components work correctly. The test suite validates Docker builds, script functionality, and end-to-end integration.

Test Suite Overview

The test suite consists of three main components:

1. Unit Tests (tests/test_run_snid.sh)

   • Validates run_snid.sh script syntax and structure
   • Tests OS detection logic
   • Verifies Docker and X11 configuration code
   • Checks for proper cleanup and error handling

2. Docker Build Tests (tests/test_docker_build.sh)

   • Verifies Docker image builds successfully
   • Validates PGPLOT installation and configuration
   • Checks SNID binary compilation
   • Ensures templates and examples are properly installed

3. Integration Tests (tests/test_integration.sh)

   • Tests end-to-end container lifecycle
   • Validates volume mounting functionality
   • Verifies environment variables and permissions
   • Tests SNID utilities (logwave, plotlnw)

Running Tests Locally

Run All Tests

./tests/run_all_tests.sh

Run Only Quick Tests (Skip Integration)

./tests/run_all_tests.sh --quick

Run Specific Test Suites

# Unit tests only
./tests/test_run_snid.sh

# Docker build tests only
./tests/test_docker_build.sh

# Integration tests only
./tests/test_integration.sh

Prerequisites for Testing

• Docker must be installed and running
• The required tarballs (snid-5.0.tar.gz and templates-2.0.tgz) must be present in the project root
• Test scripts must be executable (run chmod +x tests/*.sh if needed)

Continuous Integration

This project uses GitHub Actions for continuous integration. The CI workflow automatically runs on:

• Pushes to master, main, or develop branches
• Pull requests targeting these branches
• Manual workflow triggers

The CI pipeline includes:

• ✓ Quick validation tests (script syntax, file checks)
• ✓ Docker build verification
• ✓ Integration testing
• ✓ Multi-platform compatibility checks (Linux and macOS)

View the CI status and test results in the Actions tab of the GitHub repository.

Test Output

Tests provide clear pass/fail indicators with color-coded output:

• ✓ Green indicates passed tests
• ✗ Red indicates failed tests
• ⊘ Yellow indicates skipped tests

Each test suite provides a summary showing:

• Total tests run
• Number of passed tests
• Number of failed tests
• Detailed failure messages (if any)

Troubleshooting Tests

Missing Tarballs: If tests are skipped due to missing tarballs, download them from Stéphane Blondin's website and place them in the project root.

Docker Not Running: Ensure Docker Desktop is running before executing tests. The test suite will automatically detect if Docker is unavailable and skip relevant tests.

Permission Errors: If you encounter permission errors, ensure test scripts are executable:

chmod +x tests/*.sh