Getting Started

Getting Started

What is this?

A one-time setup of your computer: the code, one conda environment with every tool, and the safety checks.

Why does it matter?

Everyone runs the same tested tool versions, so a build made on your laptop matches one made on anyone else's.

What do I do?

Three things: install conda, clone, run one setup script. About 20 minutes, mostly waiting.

Works on macOS (Apple Silicon or Intel) and on Windows through WSL2. Docker is not needed (see Why conda and not Docker? below).

flowchart LR
    A["Install Miniforge<br/>(once per computer)"] --> B["git clone<br/>the repository"]
    B --> C["bash scripts/build_env.sh<br/>env + checks + git hooks"]
    C --> D["conda activate<br/>pekosz-nextstrain"]
    D --> E["Ready:<br/>Tutorial 1"]

Loading

Setup in five boxes. The setup script does the heavy lifting.

Why conda and not Docker?

Warning

The Nextstrain Docker runtime is no longer supported for this pipeline. Older instructions (the previous tutorial/README.md and tutorial slides) set things up with Docker Desktop, nextstrain setup docker and nextstrain shell. If you still have that setup, switch to the conda environment below.

Earlier versions of this pipeline ran inside the Nextstrain Docker runtime. In practice, lab members ran into two problems with it:

1. Viewing builds locally was unreliable. nextstrain view serves the trees from inside the Docker container on localhost, and connecting a web browser to that address often failed, especially on Windows, where the container sits behind both Docker Desktop and WSL2.
2. The reports need more than the Docker image has. The surveillance report and run report use extra Python packages (see the disclaimer below).

The custom conda environment (pekosz-nextstrain, built by scripts/build_env.sh) fixes both. Every tool runs directly in your terminal, so auspice view serves the trees at http://localhost:4000 with no container in between, and the environment contains every dependency of the builds and the reports, with tested versions that are the same on macOS and WSL.

Caution

Disclaimer: Docker may not support report generation. The Nextstrain Docker image provides the tools for the tree builds (Snakemake, augur, Nextclade), but it may not include the additional dependencies the reporting stages need: Altair and vl-convert (figures), marimo (the live report app), itables (interactive tables), python-pptx (the slide deck), openpyxl (the Excel workbook) and matplotlib (the run report). Inside Docker, the surveillance_report rule and marimo run scripts/report.py may fail, and the end-of-run report may only print a warning. Use the conda environment for every run. If you must use Docker for a one-off build, run it with --config surveillance_report=false and build the report afterwards from the conda environment with python scripts/report.py (Step 4).

What you need

• A terminal: Terminal on macOS; on Windows, the Ubuntu terminal of WSL2
• git (preinstalled on macOS; sudo apt install git on WSL)
• An internet connection (the build downloads current Nextclade datasets)
• Optional but handy:
  • Positron IDE as a text editor
  • Snakemake Language Extension for Snakemake syntax highlighting
  • SQLite Viewer Extension to inspect fludb.db

1. Install Miniforge (conda)

Miniforge provides conda, set up for the conda-forge channel (no Anaconda licence needed).

macOS

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Windows (WSL2): install WSL2 from an administrator PowerShell with wsl --install, restart, open Ubuntu from the Start menu, then run the same two commands in the Ubuntu terminal.

Accept the licence and the default location, and answer yes when asked to initialise conda. Close the terminal and open a new one: your prompt now starts with (base).

An existing Anaconda or Miniconda installation also works (conda 23.10 or newer). The environment only uses the conda-forge and bioconda channels.

2. Clone the repository

git clone https://github.com/Pekosz-Lab/nextstrain.git
cd nextstrain

All commands in this wiki are run from this top-level nextstrain folder (the one containing Snakefile). In Positron: File > Open Folder, pick nextstrain (not a subfolder), then Terminal > New Terminal.

Important

On WSL, clone into your Linux home (cd ~ first), not under /mnt/c/.... Builds on the Windows drive are many times slower and can fail on file permissions.

Cloud-synced folders (OneDrive, Dropbox) work, but the sync client copies source/ (GISAID data) to the cloud and can interfere with git. Never share the repository folder through a sync link. If you can, keep your clone outside synced folders.

3. Build the environment

bash scripts/build_env.sh

This one command:

1. Creates (or updates) the pekosz-nextstrain conda environment from workflow/envs/environment.yml, with strict conda-forge/bioconda channel priority.
2. Turns on the data-protection git hooks for your clone (git config core.hooksPath .githooks; see Data Protection), and creates the empty drag-and-drop folders source_prep/runs/ and source_prep/output/ (Step 1). Git never tracks them because they hold private data.
3. Checks every tool (Snakemake, augur, Nextclade, MAFFT, IQ-TREE, seqkit, BLAST, csvtk) and Python package, and runs tiny alignment, tree, BLAST and report tests. Wait for All N checks passed.

Then activate the environment in every new terminal:

conda activate pekosz-nextstrain

Situation	Command
Update after environment.yml changes	bash scripts/build_env.sh
Rebuild from scratch	bash scripts/build_env.sh --recreate
Apple Silicon solve fails	bash scripts/build_env.sh --intel (Intel build under Rosetta 2)
Re-run the checks only	bash scripts/build_env.sh --check
Also test Nextclade dataset downloads	bash scripts/build_env.sh --check --network
Exact tested versions (lockfile)	bash scripts/build_env.sh --locked (create the lockfile once with bash scripts/build_env.sh --lock)
All options	bash scripts/build_env.sh --help

Prefer mamba or micromamba? Create the environment yourself, then run the checks:

CONDA_CHANNEL_PRIORITY=strict mamba env create -f workflow/envs/environment.yml
# or: micromamba create -n pekosz-nextstrain -f workflow/envs/environment.yml
bash scripts/build_env.sh --check
git config core.hooksPath .githooks      # the script would have done this for you

4. Check your setup

git config --get core.hooksPath     # must print .githooks
snakemake --version                 # prints a 9.x version

You are ready. Real data needs access first: see Step 1: Source Data Preparation.

Changing the environment

Never pip install or conda install into pekosz-nextstrain by hand: your environment would silently differ from everyone else's. Changing environment.yml is a Tier 3 change (Best Practices): edit the file, run bash scripts/build_env.sh and --check, run Tutorial 1, regenerate the lockfile (--lock) and commit both files together, listing the version changes in the commit message. Every run records its tool versions (Step 4).

Troubleshooting / FAQ

• command not found: snakemake (or augur, nextclade...): the environment is not active. Run conda activate pekosz-nextstrain.
• The environment is broken or out of date: bash scripts/build_env.sh --recreate.
• Apple Silicon build fails: install Rosetta 2 once (softwareupdate --install-rosetta --agree-to-license), then bash scripts/build_env.sh --intel.
• The script warns the repository is on the Windows drive: re-clone inside WSL (cd ~ && git clone ...).
• core.hooksPath prints nothing: run git config core.hooksPath .githooks.
• I set up with Docker from the older instructions. You don't need to uninstall Docker, but don't run the pipeline from nextstrain shell anymore. Follow steps 1 to 4 on this page, then use conda activate pekosz-nextstrain in place of nextstrain shell, and auspice view in place of nextstrain view. See Why conda and not Docker?.

Next step → Tutorial 1: Your First Build