feat: add docker image & overall script

.github/workflows/docker.yml

@@ -0,0 +1,73 @@
+#
+name: Create and publish a Docker image
+
+# Configures this workflow to run every time a change is pushed to the branch called `release`.
+on:
+  push:
+    branches: ['main', 'dev-seas5']
+
+# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+      #
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
+      - name: Log in to the Container registry
+        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      # Must login to use the hardened base images.
+      - name: Log in to Docker Hub
+        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
+        with:
+          registry: dhi.io
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
+      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see [Usage](https://github.com/docker/build-push-action#usage) in the README of the `docker/build-push-action` repository.
+      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@v7
+        with:
+          platforms: linux/amd64,linux/arm64
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see [Using artifact attestations to establish provenance for builds](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds).
+      - name: Generate artifact attestation
+        uses: actions/attest@v4
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true

.python-version

@@ -0,0 +1 @@
+3.13

Dockerfile

@@ -0,0 +1,28 @@
+# Requires login to dhi.io container registry with free user creds
+# docker login dhi.io --username <your-username>
+FROM dhi.io/debian-base:trixie-debian13-dev
+
+RUN apt-get update && \
+    apt-get install -y cdo=2.5.1-1 \
+        unzip=6.0-29 \
+        nco=5.3.3-1 && \
+    rm -rf /var/lib/apt/lists/*
+ENV USER=nonroot \
+        GROUP=nonroot
+# install uv
+COPY --chown=$USER:$GROUP --from=ghcr.io/astral-sh/uv:0.11.7 /uv /uvx /bin/
+
+WORKDIR /home/${USER}
+USER $USER
+
+COPY --chown=$USER:$GROUP uv.lock uv.lock
+COPY --chown=$USER:$GROUP pyproject.toml pyproject.toml
+
+RUN touch README.md && uv sync --no-dev 
+
+COPY --chown=$USER:$GROUP mkforcing/*.py mkforcing/
+COPY --chown=$USER:$GROUP mkforcing/*.sh mkforcing/
+
+COPY --chown=$USER:$GROUP run_get_forcing.sh run_get_forcing.sh
+
+ENTRYPOINT [ "./run_get_forcing.sh" ]

README.md

@@ -11,5 +11,31 @@ simulations.
 
 Please check the documentation at https://hpscterrsys.github.io/eCLM_atm-forcing-generator/INDEX.html
 
+## Docker usage
+
+To run an opinionated script to download and process either ERA5 or SEAS5 run the following:
+
+Ensure CDSAPI_KEY & CDSAPI_URL are both set to appropriate values and domain.lnd.DE-RuS.240717.nc is your domainfile.
+
+Build the image
+
+```bash
+docker build -t atm-forcing .
+```
+
+```bash
+mkdir -p  data/2026-01
+docker run -e CDSAPI_KEY=$CDSAPI_KEY -e CDSAPI_URL=$CDSAPI_URL  -it  -v $(pwd)domain.lnd.DE-RuS.240717.nc:/home/nonroot/domain.nc -v $(pwd)/data/2026-01:/home/nonroot/2026-01   atm-forcing ERA5 2026 01
+```
+
+or for SEAS5
+
+```bash
+mkdir -p  data/2026-01
+docker run -e CDSAPI_KEY=$CDSAPI_KEY -e CDSAPI_URL=$CDSAPI_URL  -it  -v $(pwd)domain.lnd.DE-RuS.240717.nc:/home/nonroot/domain.nc -v $(pwd)/data/2026-01:/home/nonroot/2026-01   atm-forcing SEAS5 2026 01
+```
+
+The resulting data can be found at data/2026-01.
+
 ## License
 eCLM atmospheric forcing generator is open source software and is licensed under the [MIT-License](https://github.com/HPSCTerrSys/eCLM_atm-forcing-generator/blob/master/LICENSE).

mkforcing/custom_request_ERA5.py

@@ -28,7 +28,7 @@
     ],
     "data_format": "netcdf",
     "download_format": "unarchived",
-    "area": [50.870906, 6.4421445, 50.870906, 6.4421445]      # Selhausen
+    "area": [51, 6, 50, 7]      # Selhausen
     # "area": [74, -42, 20, 69] # Europe
 }
 

mkforcing/custom_request_SEAS5_06h.py

@@ -30,7 +30,7 @@
     "day": ["01"],
     "leadtime_hour": [str(h) for h in range(0, 5161, 6)],
     "data_format": "netcdf",
-    "area": [50.870906, 6.4421445, 50.870906, 6.4421445]      # Selhausen
+    "area": [51, 6, 50, 7]      # Selhausen
     # "area": [74, -42, 20, 69] # Europe
 }
 

mkforcing/custom_request_SEAS5_24h.py

@@ -30,7 +30,7 @@
     "day": ["01"],
     "leadtime_hour": [str(h) for h in range(0, 5161, 6)],
     "data_format": "netcdf",
-    "area": [50.870906, 6.4421445, 50.870906, 6.4421445]      # Selhausen
+    "area": [51, 6, 50, 7]      # Selhausen
     # "area": [74, -42, 20, 69] # Europe
 }
 

mkforcing/custom_request_SEAS5_const.py

@@ -30,7 +30,7 @@
     "day": ["01"],
     "leadtime_hour": [str(h) for h in range(0, 5161, 6)],
     "data_format": "netcdf",
-    "area": [50.870906, 6.4421445, 50.870906, 6.4421445]      # Selhausen
+    "area": [51, 6, 50, 7]      # Selhausen
     # "area": [74, -42, 20, 69] # Europe
 }
 

mkforcing/download_ERA5_input.py

@@ -26,6 +26,23 @@
 # import sys
 import os
 import tempfile
+import xarray as xr
+import numpy as np
+
+def domain_to_bbox(domain_file: str) -> tuple[int, int, int, int]:
+    """
+    extract the rounded integer bbox of the provided domain file
+    for use in sending to CDS API requests (e.g., for ERA5 or SEAS5 data)
+    """
+    arr = xr.open_dataset(domain_file, engine="netcdf4")
+    x_values = arr.xc.values
+    y_values = arr.yc.values
+    return (
+        int(np.ceil(y_values.max())),
+        int(np.floor(x_values.min())),
+        int(np.floor(y_values.min())),
+        int(np.ceil(x_values.max())),
+    )
 
 
 def generate_days(year, month):
@@ -216,6 +233,14 @@ def generate_datarequest(year, monthstr, days,
         default="reanalysis-era5-single-levels",
         help="CDS dataset name (default: reanalysis-era5-single-levels)"
     )
+    parser.add_argument(
+        "--domainfile",
+        type=str,
+        required=False,
+        default=None,
+        help="The path to the domain file, used to calculate bbox for requests"
+    )
+
 
     # Parse command-line arguments
     args = parser.parse_args()
@@ -297,6 +322,11 @@ def generate_datarequest(year, monthstr, days,
         # Compute all days in the month
         days = generate_days(year, month)
         print(f"Using all days in month: {len(days)} days")
+
+    domainfile = args.domainfile
+    if domainfile and custom_request and 'area' in custom_request:
+        bbox = domain_to_bbox(domainfile)
+        custom_request["area"] = bbox
 
     print(f"Downloading ERA5 data for {year}-{monthstr}")
     print(f"Dataset: {custom_dataset}")

mkforcing/merge_seas5.sh

@@ -0,0 +1,17 @@
+YEAR=$1
+NUM_ENS=${2:-51}
+
+mkdir -p "${YEAR}"
+for ((i=1; i<=NUM_ENS; i++)); do
+  ens=$(printf "%05d" $i)
+  files=( ${YEAR}-*/real_${ens}/${YEAR}-*.nc )
+  if [ -e "${files[0]}" ]; then
+    num_files=${#files[@]}
+    echo "Processing ensemble ${ens}: merging ${num_files} files"
+    mkdir -p "${YEAR}/real_${ens}"
+    cdo -f nc4c mergetime "${files[@]}" "${YEAR}/real_${ens}/${YEAR}-01.nc"
+  else
+    echo "Ensemble ${ens}: no files found, skipping"
+  fi
+done
+echo "Merging complete for year ${YEAR} with ${NUM_ENS} ensemble members."

mkforcing/prepare_ERA5_input.sh

@@ -58,6 +58,7 @@ parse_arguments() {
             iyear) iyear="$value" ;;
             author) author="$value" ;;
             email) email="$value" ;;
+            domainfile) domainfile="$value" ;;
             *) echo "Warning: Unknown parameter: $key" ;;
         esac
     done

mkforcing/prepare_SEAS5_input.sh

@@ -46,6 +46,7 @@ parse_arguments() {
             author) author="$value" ;;
             email) email="$value" ;;
             nens) nens="$value" ;;
+            domainfile) domainfile="$value" ;;
             *) echo "Warning: Unknown parameter: $key" ;;
         esac
     done

pyproject.toml

@@ -0,0 +1,12 @@
+[project]
+name = "eclm-atm-forcing-generator"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "cdsapi>=0.7.7",
+    "netcdf4>=1.7.4",
+    "numpy>=2.4.4",
+    "xarray>=2026.4.0",
+]

run_get_forcing.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+set -e
+if [[ -z "$1" || -z "$2" || -z "$3" ]]; then
+    echo "Usage: $0 MODE YEAR MONTH"
+    exit 1
+fi
+
+MODE=$1
+YEAR=$2
+MONTH=$3
+
+mkdir -p ${YEAR}-${MONTH}
+if [[ "$MODE" == "ERA5" ]]; then
+    mkdir -p data
+    uv run mkforcing/download_ERA5_input.py \
+        --year $YEAR \
+        --month $MONTH \
+        --dirout data \
+        --request "${HOME}/mkforcing/custom_request_ERA5.py" \
+        --domainfile "${HOME}/domain.nc"
+    unzip "data/download_era5_${YEAR}_${MONTH}.zip" -d data/
+    uv run mkforcing/dewpoint_to_specific_humidity.py data/data_stream-oper_stepType-instant.nc
+    uv run mkforcing/2m_to_10m_conversion.py data/data_stream-oper_stepType-instant.nc
+    mkforcing/prepare_ERA5_input.sh \
+        lrenametime=true lmeteo=false \
+        lunzip=false wgtcaf=../wgtdis_era5caf_to_domain.nc \
+        griddesfile=../domain_griddef.txt iyear=$YEAR \
+        imonth=$MONTH \
+        pathdata=../data \
+        lwgtdis=true lgriddes=true domainfile="${HOME}/domain.nc"
+
+else
+    mkdir cdsapidwn_SEAS5_const
+    uv run mkforcing/download_ERA5_input.py \
+        --year $YEAR --month ${MONTH} \
+        --dirout cdsapidwn_SEAS5_const \
+        --request "${HOME}/mkforcing/custom_request_SEAS5_const.py" \
+        --domainfile "${HOME}/domain.nc"
+    uv run mkforcing/download_ERA5_input.py \
+        --year ${YEAR} --month ${MONTH} \
+        --dirout cdsapidwn_SEAS5_24h \
+        --request "${HOME}/mkforcing/custom_request_SEAS5_24h.py" \
+        --domainfile "${HOME}/domain.nc"
+    uv run mkforcing/download_ERA5_input.py \
+        --year ${YEAR} --month ${MONTH} \
+        --dirout cdsapidwn_SEAS5_06h \
+        --request "${HOME}/mkforcing/custom_request_SEAS5_06h.py" \
+        --domainfile "${HOME}/domain.nc"
+    mkdir -p cdsapidwn_SEAS5
+    uv run mkforcing/seas5_daily_to_6hourly.py \
+        --const cdsapidwn_SEAS5_const/download_era5_${YEAR}_${MONTH}.nc \
+        --daily cdsapidwn_SEAS5_24h/download_era5_${YEAR}_${MONTH}.nc \
+        --hourly cdsapidwn_SEAS5_06h/download_era5_${YEAR}_${MONTH}.nc \
+        --output cdsapidwn_SEAS5/download_era5_${YEAR}_${MONTH}.nc \
+        --frequency 3 --include-hour-zero
+    uv run mkforcing/orography_to_elevation.py \
+        cdsapidwn_SEAS5/download_era5_${YEAR}_${MONTH}.nc
+    uv run mkforcing/mslp_to_sp.py \
+        cdsapidwn_SEAS5/download_era5_${YEAR}_${MONTH}.nc \
+        --elevation-var elevation
+    uv run mkforcing/dewpoint_to_specific_humidity.py \
+        cdsapidwn_SEAS5/download_era5_${YEAR}_${MONTH}.nc
+    uv run mkforcing/2m_to_10m_conversion.py \
+        cdsapidwn_SEAS5/download_era5_${YEAR}_${MONTH}.nc
+
+    mkforcing/prepare_SEAS5_input.sh \
+        lwgtdis=true lgriddes=true \
+        domainfile="${HOME}/domain.nc" \
+        griddesfile=../domain_griddef.txt \
+        wgtcaf=../wgtdis_era5caf_to_domain.nc \
+        iyear=${YEAR} imonth=${MONTH} \
+        pathdata=../cdsapidwn_SEAS5
+fi