Fre-cli container files

.github/workflows/update_container_image.yaml

@@ -0,0 +1,46 @@
+name: Docker Image CI/CD
+
+on:
+  push:
+    branches:
+      - main #  Trigger on push to the main branch
+    # Build container if these files are changed
+    paths:
+      - 'container-files/Dockerfile-frecli'
+      - 'container-files/runscript.sh'
+      - 'container-files/cylc-flow-tools.yaml'
+      - '.github/workflows/update_container_image.yaml'
+  repository_dispatch:
+    types: [fre-cli-release]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: "noaa-gfdl/ubuntu-20-frecli-2025/"
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read   # Allow checkout
+      packages: write  # Allow pushing to GitHub Packages/GHCR
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Ensure tags are available
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: . # Directory containing the Dockerfile
+          file: ./container-files/Dockerfile-frecli
+          push: true
+          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.set_tag.outputs.docker_tag }}

container-files/Dockerfile-frecli

@@ -0,0 +1,33 @@
+FROM condaforge/mambaforge:24.9.2-0 as builder
+#LABEL maintainer "Ciheim Brown"
+## Description ##
+# condaforge is based on a stripped down ubuntu image.  We need some extra bits for frerun + fremake
+####
+
+# Set where the conda installation goes
+ARG conda_location=/app/cylc-flow-tools
+
+# Change to encrypted HTTP
+RUN sed -i 's/http/https/g' /etc/apt/sources.list
+
+# apt installs to /usr/bin/
+RUN apt update \
+  && apt -y install uuid-runtime time csh python bc 
+
+# Update conda because this build container may be stale.
+RUN conda update -n base -c conda-forge conda
+
+# Copy runscript in container and make it executable
+COPY ppp/runscript.sh /app/exec/runscript.sh
+RUN chmod +x /app/exec/runscript.sh
+
+# Set up conda environment directory for cylc workflow
+COPY ppp/cylc-flow-tools.yaml ${conda_location}/cylc-flow-tools.yaml
+RUN mamba env create --file ${conda_location}/cylc-flow-tools.yaml -p ${conda_location}
+
+# Maybe perhaps tag an external mounted volume /mnt2 as being safe...
+# RUN git config --global --add safe.directory /mnt2
+
+RUN conda install urwid==2.*
+
+ENTRYPOINT ["/bin/bash"]

container-files/README.md

@@ -0,0 +1,103 @@
+# Post-Processing Container
+
+Previously, many GFDL workflows and configurations have only been accessible on gitlab. This is disadvantageous for outside collaboration, flexibility, community development. While the FRE workflow can now be conda installed, another deployment method of containerization has been developed. Containerzation of the FRE workflow at GFDL bolsters portability while also simplifying the environment set-up for the user. With the environment set-up done through the container build and runscript, this post-processing container work allows for more effective sharing of the workflow.
+
+## BUILDING
+
+**In order to build the container, the user needs to have podman access on gaea. If needed, put in a helpdesk ticket.**
+
+Files used to build container:
+
+- Dockerfile-ppp
+- cylc-flow-tools environment yaml
+- runscript.sh
+
+The container will house the fre-cli tools and subtools, and any necessary packages needed for those tools.
+
+Using podman and apptainer to build, follow these steps:
+
+```
+## Clone the HPC-ME repository
+git clone git@gitlab.gfdl.noaa.gov:fre/HPC-ME.git
+
+## Navigate into the HPC-ME repo folder
+cd HPC-ME
+
+## Build a container image
+podman build -f Dockerfile-ppp -t 2025
+
+## Save the image to a local tar file
+# It is recommended to name the container after the post-processing experiment name
+podman save -o [name of container].tar localhost/2025
+
+## Create the singularity image file (sif) from the tar file
+apptainer build --disable-cache [name of container].sif docker-archive://[name of container].tar
+```
+
+## SETUP
+Now that the FRE workflows container is created, certain files and directories must be made accessible.
+
+#### <ins>Repos and Configuration files
+
+In order to run the post-processing workflow, certain repositories and files are needed: 
+
+1. `fre-workflows` cloned repository
+    - Can be found here: https://github.com/NOAA-GFDL/fre-workflows 
+
+2. Directory that will include folders and files for container set-up and running (could be named `ppp-setup` for example)
+    - The setup/output directory consists of a few subdirectories: pp, ptmp, and temp (these are created through the runscript.sh in this repository for the container)
+    - ***Ensure you create the empty `ppp-setup` folder in an area with enough space as this is where the post-processing run output will be populated.***
+
+3. Yaml configuration files are also needed. 
+    - Publicly available example yaml configuration files can be found here: https://github.com/NOAA-GFDL/fre-examples 
+
+#### <ins>Data files
+
+Additionally, history files and grid spec files are needed.
+
+**If on Gaea**, history files and grid spec files are usually available in a certain location; retrieve their locations
+
+- Paths to the history folder and grid spec file will be mounted into the container as read only folders/files 
+
+**If not on Gaea**, history file and grid spec data should be transferred to the `ppp-setup` location in:
+
+- `ppp-setup/history/`
+- `ppp-setup/[experiment]_grid/`
+
+FOR CLOUD USERS: Preparing for cloud usage requires history files and container image/runscript to be transferred to the cloud resource. The recommended method of file transfer is with Globus in which files should be transferred to the cloud resource’s lustre folder. 
+
+Refer to globus documentation here: [Globus Online Data Transfer](https://docs.rdhpcs.noaa.gov/data/globus_online_data_transfer.html)
+
+#### <ins>Configuration Edits
+
+Regarding the yaml configurations, some paths need to be edited to reference the file location mounted inside the container. These include: 
+
+- `&GRID_SPEC96` "/mnt/[experimentname]_grid/[gridSpec file]
+- `history_dir`: "/mnt/history"
+- `pp_dir`: "/mnt/pp" 
+- `ptmp_dir`: "/mnt/ptmp"
+
+## RUNNING 
+
+To run the container, follow these steps:
+
+```
+## Use apptainer or singularity to run
+# Make sure directories are writable
+# Bind in necessary locations (setup folder, workflow folder, data locations)
+apptainer exec --writable-tmpfs --bind [Path/to/setup/folder]:/mnt --bind [Path/to/fre-worflows]:/mnt2 --bind [Path/to/gridspec location]:/mnt/[experiment-name]_grid:ro --bind [Path/to/history/files]:/mnt/history:ro [Path/to/created/container] /app/exec/runscript.sh
+```
+NOTE: It is essential that binding is done correctly as the container’s runscript relies heavily on these paths.
+
+Here,
+- `--writable-tmpfs` allows files in the container to be editable, but temporarily (as long as the container is running)
+- `--bind` mounts that  
+- `ro` refers to `read-only`, so that data files are not corrupted in any way. 
+
+At this point, the container’s runscript will begin to run. User input is required, listing the experiment, platform, target, and post-processing yaml file.
+
+The experiment will be installed, configuration files will be validated, and the experiment should kick off.
+
+## REVIEW
+
+The setup-output directory created earlier will hold pp output for review. It will also hold a newly created cylc-run directory.

container-files/cylc-flow-tools.yaml

@@ -0,0 +1,12 @@
+name: cylc-flow-tools
+channels: 
+  - conda-forge
+  - NOAA-GFDL
+dependencies:
+  - noaa-gfdl::hsm
+  - noaa-gfdl::fre-cli ==2025.04
+  - noaa-gfdl::fre-python-tools
+  - conda-forge::nco
+  - conda-forge::rsync
+  - conda-forge::make
+  - conda-forge::vim