documentation for running outside of biowulf

[kelly-sovacool]

currently this page is quite buried: https://ccbr.github.io/CHAMPAGNE/latest/nextflow/

the quickstart guide assumes users are using biowulf

we want to support any environment/executor that nextflow supports, e.g. local macs, aws, etc.

[kelly-sovacool]

we should probably link to the nextflow installation docs https://docs.seqera.io/nextflow/install

[kelly-sovacool]

showcase --max_memory 24.GB --max_cpus 8 for local execution, also mention editing conf/base.config if necessary

[kelly-sovacool]

Thanks Sophia @caffiendFrog and Padma @padmashris!

[padmashris]

Here are some notes from debugging errors from running it locally on my machine:

Running CHAMPAGNE locally on macOS

1. Prerequisites

Requirement	Notes
Nextflow	25.10.0 (pipeline is built/tested on this version — see Install Nextflow)
Java	17 (confirm with java -version; on Apple Silicon this is typically installed via brew install openjdk@17)
Bash	System /bin/bash on macOS needs to be upgraded (see Upgrade bash)
Docker	Docker Desktop, running, with enough memory/CPU allocated to the Docker VM

2. Install Nextflow

curl -s https://get.nextflow.io | bash
chmod +x nextflow
mkdir -p $HOME/.local/bin/
mv nextflow $HOME/.local/bin/
export PATH="$PATH:$HOME/.local/bin"

Important: the installer/curl script will pull the latest Nextflow release, which is newer than what CHAMPAGNE is built against. Pin the version at runtime with NXF_VER:

NXF_VER=25.10.0 nextflow run main.nf -profile test,docker

Confirm the environment with:

nextflow info

3. Upgrade bash

macOS ships with an ancient bash (3.2, from 2007) that isn't sufficient for some pipeline scripts. Install a current version via Homebrew:

brew install bash

Add the new bash to /etc/shells and confirm it's picked up (which bash / bash --version) before launching the pipeline.

4. Config changes for a local laptop run

Several values in the pipeline's config are Biowulf-specific and need to be localized/adjusted before a run will work on a laptop.

4a. base.config: memory limits

The default resource config assumes cluster-scale memory (e.g. DEEPTOOLS:BIGWIG_SUM requests 200 GB), which will fail on a laptop:

Caused by:
  Process requirement exceeds available memory -- req: 200 GB; avail: 24 GB

Fix: either edit conf/base.config to scale down the memory/cpus directives to match your machine, or cap them at runtime with --max_cpus and --max_memory. Note --max_memory must be passed as a string with units (an unquoted number like 20 is rejected):

NXF_VER=25.10.0 nextflow run main.nf -profile test,docker -resume \
  --max_cpus 8 --max_memory 20GB

4b. Blacklist file: make it local

By default the blacklist path points to a Biowulf-only location:

blacklist : /data/CCBR_Pipeliner/db/PipeDB/Indices/hg38_basic/indexes/hg38.blacklist_v3.chrM.chr_rDNA.fa

which isn't reachable from a laptop (ERROR ~ No such file or directory: ...). Fix:

1. Copy/download the blacklist file to the repo directory (or another local path).
2. Point blacklist at the local, decompressed file — the pipeline only accepts .bed or .fasta/.fa. Within conf/test.config:

blacklist = '/data/CCBR_Pipeliner/db/PipeDB/Indices/hg38_basic/indexes/hg38.blacklist_v3.chrM.chr_rDNA.fa'

to

blacklist = '/YOUR_FOLDER/hg38.blacklist_v3.chrM.chr_rDNA.fa'

5. Running the pipeline

Once the above is in place, launch a test run:

NXF_VER=25.10.0 nextflow run main.nf -profile test,docker -resume \
  --max_cpus 8 --max_memory 20GB

The parameters --max_cpus and --max_memory will be based on your machine's capabilities.

• Always include -resume after the first attempt — Nextflow will reuse cached/completed tasks and only re-run what previously failed, which saves a lot of time while iterating on config fixes.

Example successful run summary

Completed at: 17-Jul-2026 15:06:46
Duration    : 1h 1m 17s
CPU hours   : 7.5 (10.5% cached, 0% failed)
Succeeded   : 80
Cached      : 123
Ignored     : 2
Failed      : 2

6. Troubleshooting quick reference

Error message	Cause	Fix
zsh: command not found: nextflow	Nextflow not installed / not on PATH	Install per Section 2
Error nextflow.config:4:20: outputDir is not defined	Nextflow version mismatch	Run with NXF_VER=25.10.0
ERROR ~ No such file or directory: /data/CCBR_Pipeliner/...	Biowulf-only path (blacklist, etc.)	Localize the file, see section 4b
Process requirement exceeds available memory -- req: 200 GB; avail: 24 GB	base.config sized for a cluster	Pass --max_cpus/--max_memory (with units, e.g. 20GB) or edit conf/base.config
--max_memory (20): Value is [integer] but should be [string]	Missing units on --max_memory	Use --max_memory 20GB, not --max_memory 20