From 12e0e0f1928ce6ffd480b27186a3d60d6e754571 Mon Sep 17 00:00:00 2001 From: Joseph Glaser Date: Fri, 23 Feb 2024 19:32:21 +0000 Subject: [PATCH] Initial commit to merge documentation of ReadMe and set up Docker CLI --- .github/workflows/test_Docker.yml | 29 +++++++++++++++ README.md | 41 +++++++++++++++++++++ containers/README.md | 26 ------------- containers/{Singularity => Singularity.def} | 0 4 files changed, 70 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/test_Docker.yml delete mode 100644 containers/README.md rename containers/{Singularity => Singularity.def} (100%) diff --git a/.github/workflows/test_Docker.yml b/.github/workflows/test_Docker.yml new file mode 100644 index 0000000..6d46226 --- /dev/null +++ b/.github/workflows/test_Docker.yml @@ -0,0 +1,29 @@ +name: 'Docker Build (Ubuntu)' + +on: [push] + +#on: +# push: +# paths: +# - 'containers/Dockerfile' + +jobs: + build-apptainer-image: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest] + max-parallel: 5 + steps: + - uses: actions/checkout@v4 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build Test Docker Image + uses: docker/build-push-action@v5 + with: + context: containers/Dockerfile + push: false + tags: ${{ env.TEST_TAG }} + - name: Test Docker + run: | + docker run --rm ${{ env.TEST_TAG }} diff --git a/README.md b/README.md index be4468d..d8a0159 100644 --- a/README.md +++ b/README.md @@ -27,3 +27,44 @@ For Linux 64, Open MPI is built with CUDA awareness but this support is disabled In addition, the UCX support is also built but disabled by default. To enable it, first install UCX (`conda install -c conda-forge ucx`). Then, set the environment variables `OMPI_MCA_pml="ucx"` and `OMPI_MCA_osc="ucx"` before launching your MPI processes. Equivalently, you can set the MCA parameters in the command line: `mpiexec --mca pml ucx --mca osc ucx ...` Note that you might also need to set `UCX_MEMTYPE_CACHE=n` for CUDA awareness via UCX. Please consult UCX's documentation for detail. + +## Docker +Docker is a program which builds interactive virtual machines (containers) that are designed to be somewhat integrated with the host machine. They are easily deployed on many different hardware infrastructures, but are often not allowed on High Performace Computing (HPC) machines due to the security risk it poses ([read more](https://linuxconcept.com/getting-privileged-access-inside-a-docker-container-your-guide-to-enhanced-control/)). However, it is exceedingly useful for JupyterHub instances or quick roll-out during workshops. + +### To Build the Container: +To build the Docker image, follow the latest instructions for the `docker build` command found [here](https://docs.docker.com/reference/cli/docker/image/build). + +## Apptainer/Singularity + +Apptainer (former name: Singularity) is a program to build virtual machines (containers) with desired OS and programs. These can be easily deployed and ran on other computers. +Containers are build based on the recipies called "definition files", here we provide a definition file `Singularity`. Note, sometimes definition files have an extension `.def`, which we also refer to in the instructions below. + +The current definition file contains `tempo2`, `enterprise`, and other primary packages for IPTA DR3 data analyses. + +### To Build the Container: +To build the Apptainer image (`IPTA-Env.sif`), you need to first have Apptainer installed on your machine as well as administrator access. If you plan to use this image on an HPC resource, you should contact your HPC administrator to build the image for you to ensure proper linkage with the desired MPI libraries and relevant compilers. Once installed, a system adminstrator can build the container via: + +``` +sudo apptainer build IPTA-Env.sif containers/Singularity.def +``` + +### To Browse the Container: +Once installed and the image is built, any user of that local machine can access the Apptainer image via a shell instance by running: +``` +apptainer shell --bind "/virtual_home_directory/:$HOME" IPTA-Env.sif` +``` +Where `/virtual_home_directory/` is the path to your home directory on your local machine. + +### For Building Containers Inside Windows WSL via Ubuntu + +In Windows Store, there is [Ubuntu app](https://apps.microsoft.com/detail/9pdxgncfsczv?hl=en-US&gl=US) that allows to run the popular Linux OS as a command-line shell in Windows. However, by default, it is based on Windows Subsystems for Linux v1 (WSL1). Make sure to upgrade from WSL1 to WSL2. You can read more about this procedure via the [official guide from Microsoft](https://learn.microsoft.com/en-us/windows/wsl/install). This requires also may requre updating settings in BIOS. + +To be able to use graphical interface (PGPLOT) in tempo2 plk plugin, a proper display redirection is required: +1. From within the **Windows command-line**, obtain the local IPv4 address for the machine: `ipconfig`. +2. Open the Ubuntu app. +3. Edit the `$HOME/.bash_profile` file found in **Ubuntu** to have the following line at the end: `export DISPLAY=172.26.32.1:0.0` +4. Close the Ubuntu app. +5. Install [Xming](https://sourceforge.net/projects/xming/) for Windows, which creates an XServer instance on the Windows OS. +6. Run Xming with `-ac` argument via XLaunch. +7. Finally, open the Ubuntu app and run your commands as normal. The graphical interfaces should appear as expected via an Xmimg instance. + diff --git a/containers/README.md b/containers/README.md deleted file mode 100644 index a9143c4..0000000 --- a/containers/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Apptainer/Singularity - -Apptainer (former name: Singularity) is a program to build virtual machines (containers) with desired OS and programs. These can be easily deployed and ran on other computers. -Containers are build based on the recipies called "definition files", here we provide a definition file `Singularity`. Note, sometimes definition files have an extension `.def`, which we also refer to in the instructions below. - -The current definition file contains `tempo2`, `enterprise`, and other primary packages for IPTA DR3 data analyses. - -## To build a container: - -`sudo apptainer build new_sif_file_name.sif def_file.def` - -## To browse container content: - -`apptainer shell --bind "/virtual_home_directory/:$HOME" pulsarenv_official_20240220.sif` - -Where `/virtual_home_directory/` is a path on your local machine - -## For building containers inside Windows WSL Ubuntu (Ubuntu for Windows) - -In Windows Store, there is Ubuntu app that allows to run Ubuntu shell in Windows. However, by default, it is based on WSL1. Make sure to upgrade from WSL1 to WSL2. This requires also updating settings in BIOS. - -To be able to use graphical interface (PGPLOT) in tempo2 plk plugin, a proper display redirection is required: - -1. In .bashrc in Ubuntu, `export DISPLAY=172.26.32.1:0.0`, where the IP address (v4) can be obtained in Windows command line prompt by running `ipconfig`. -2. Install Xming for Windows. -3. Run Xming with `-ac` argument via XLaunch. Then open Ubuntu. diff --git a/containers/Singularity b/containers/Singularity.def similarity index 100% rename from containers/Singularity rename to containers/Singularity.def