Add pykernel support; add testing suite; overhaul documentation

.github/docker/Rstudio/Dockerfile

@@ -0,0 +1,64 @@
+# This Dockerfile is installing R and RStudio Server on Ubuntu 22.04.03
+# purpose of this dockerfile is to create a test environment for the ICRN manager
+# this docker is intended to mimic the NCSA ICRN JupyterHub environment
+# Use the minimal-notebook as base
+ARG JUPYTER_VERSION=latest
+FROM jupyter/minimal-notebook:${JUPYTER_VERSION}
+
+ARG ICRN_MANAGER_PATH=/sw/icrn/jupyter/icrn_ncsa_resources/tools/icrn_manager/
+ARG ICRN_KERNELS_PATH=/sw/icrn/jupyter/icrn_ncsa_resources/kernels/
+# ARG ICRN_TESTS_PATH=/sw/icrn/jupyter/icrn_ncsa_resources/tests/
+
+# Switch to root to install additional packages
+USER root
+
+WORKDIR /
+
+# Install R and its dependencies
+RUN apt update -qq && \
+    apt install -y --no-install-recommends software-properties-common dirmngr && \
+    wget -qO- https://cloud.r-project.org/bin/linux/ubuntu/marutter_pubkey.asc | tee -a /etc/apt/trusted.gpg.d/cran_ubuntu_key.asc && \
+    add-apt-repository "deb https://cloud.r-project.org/bin/linux/ubuntu $(lsb_release -cs)-cran40/" && \
+    apt install -y r-base
+
+# Installs Rstudio Server
+RUN apt install -y --no-install-recommends gdebi-core && \
+    wget https://download2.rstudio.org/server/jammy/amd64/rstudio-server-2024.12.0-467-amd64.deb && \
+    gdebi -n rstudio-server-2024.12.0-467-amd64.deb && \
+    rm -f rstudio-server-2024.12.0-467-amd64.deb
+
+# Install tidyverse and jq (required by icrn_manager)
+RUN apt update -qq && apt install --yes --no-install-recommends wget ca-certificates gnupg jq && \
+    wget -q -O- https://eddelbuettel.github.io/r2u/assets/dirk_eddelbuettel_key.asc | tee -a /etc/apt/trusted.gpg.d/cranapt_key.asc && \
+    echo "deb [arch=amd64] https://r2u.stat.illinois.edu/ubuntu jammy main" > /etc/apt/sources.list.d/cranapt.list && \
+    apt update -qq && \
+    apt install --yes --no-install-recommends  r-cran-data.table r-cran-tidyverse && \
+    apt clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Installs the jupyter-rsession-proxy
+RUN pip install jupyter-rsession-proxy && \
+    chown -R $NB_USER:users /home/$NB_USER/.cache
+
+# Switch to default working directory
+WORKDIR /home/$NB_USER
+
+RUN mkdir -p $ICRN_KERNELS_PATH && \
+ mkdir -p $ICRN_MANAGER_PATH 
+
+# Copy icrn_manager tools to /usr/local/bin for system-wide access
+COPY ./icrn_manager /usr/local/bin/icrn_manager
+COPY ./update_r_libs.sh /usr/local/bin/update_r_libs.sh
+
+# Make the icrn_manager tools executable
+RUN chmod +x /usr/local/bin/icrn_manager && \
+    chmod +x /usr/local/bin/update_r_libs.sh
+
+# eh? no. this is a shared volume; i'm pretty sure.
+# RUN chown -R $NB_USER:users /sw
+
+# Switch to default NB_USER
+USER $NB_USER
+
+# after switch, run init, so user's homedir is set up with catalog, etc.
+RUN icrn_manager kernels init $ICRN_KERNELS_PATH

.github/docker/Rstudio/cowsay_conda.sh

@@ -0,0 +1,6 @@
+icrn_manager kernels use none
+conda create --solver=libmamba -c r -y -n R_cowsay r-base=4.4.3
+conda activate R_cowsay
+Rscript -e 'install.packages("cowsay", repos="http://cran.us.r-project.org")'
+conda install -y --solver=libmamba conda-pack
+conda pack -n R_cowsay -o ~/conda-packs/R_cowsay.conda.pack.tar.gz

.github/workflows/docker-build.yml

@@ -0,0 +1,68 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'icrn_manager'
+      - 'update_r_libs.sh'
+      - '.github/docker/**'
+  pull_request:
+    branches: [ main, master ]
+    paths:
+      - 'icrn_manager'
+      - 'update_r_libs.sh'
+      - '.github/docker/**'
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=sha,prefix={{branch}}-
+          type=raw,value=latest,enable={{is_default_branch}}
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: .github/docker/Rstudio/Dockerfile
+        push: true
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+    - name: Output image info
+      run: |
+        echo "Built and pushed image: ${{ steps.meta.outputs.tags }}"
+        echo "Image digest: ${{ steps.build.outputs.digest }}" 

.github/workflows/test.yml

@@ -0,0 +1,65 @@
+name: Test ICRN Manager
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y jq tar
+
+    - name: Make scripts executable
+      run: |
+        chmod +x icrn_manager
+        chmod +x update_r_libs.sh
+        chmod +x tests/run_tests.sh
+
+    - name: Run test suite
+      run: |
+        ./tests/run_tests.sh
+
+    - name: Upload test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: test-results
+        path: tests/test_results.log
+
+  test-docker:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Build Docker image
+      run: |
+        docker build -t icrn-manager-test .github/docker/Rstudio/
+
+    - name: Run tests in Docker
+      run: |
+        docker run --rm \
+          -v $(pwd):/workspace \
+          -w /workspace \
+          icrn-manager-test \
+          bash -c "cd /workspace && ./tests/run_tests.sh"
+
+    - name: Upload Docker test results
+      uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: docker-test-results
+        path: tests/test_results.log 

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to the ICRN Kernel Manager project will be documented in this file.
+
+## [Unreleased] - 2024-07-24
+
+### Added
+- **Comprehensive Test Suite**: Added a complete test suite with 32 tests covering all major functionality
+- **Test Isolation**: Each test now runs in its own isolated environment to prevent interference
+- **Mock Data**: Tests use consistent mock kernel packages and catalogs for reliable testing
+- **Error Handling Tests**: Added tests for both success and failure scenarios
+
+### Improved
+- **Error Handling**: Enhanced error messages throughout the codebase with clear, descriptive output
+- **File Path Validation**: Added comprehensive validation for file paths and permissions
+- **update_r_libs.sh**: Improved error handling for invalid file paths and missing directories
+- **Test Reliability**: Tests now clean up after themselves and don't share state
+
+### Fixed
+- **Test Interference**: Resolved issues where tests could affect each other's results
+- **Ungraceful Failures**: Fixed cases where commands would fail with shell errors instead of clear messages
+- **Permission Issues**: Added proper permission checking before file operations
+- **Configuration Validation**: Improved validation of configuration files and directories
+
+### Technical Details
+- **Test Structure**: 
+  - `test_kernels.sh`: 13 tests covering kernel operations
+  - `test_update_r_libs.sh`: 6 tests covering R library management
+  - `test_config.sh`: 10 tests covering configuration validation
+  - `test_help.sh`: 3 tests covering help and basic commands
+- **Test Environment**: Isolated environments created in `./tests/test_env/`
+- **Mock Data**: Sample R and Python kernels with proper catalog structure
+- **Error Messages**: Standardized error message format with "ERROR:" prefix
+
+### Documentation
+- **Contributing Guide**: Added comprehensive testing section with examples
+- **Maintainer Guide**: Added testing recommendations for new kernels
+- **Troubleshooting**: Updated with improved error handling information
+- **README**: Added testing section with command examples
+
+## [Previous Releases]
+
+*Note: This changelog was started with the recent test suite and error handling improvements. Previous releases may not be documented here.*