(tutorial)=

# Tutorial: running raccoon-nf

This tutorial walks through the complete workflow lifecycle in GLACIER — adding a workflow repository, installing it, examining its parameters, and launching a test run — using the [raccoon-nf](https://github.com/artic-network/raccoon-nf) pipeline as an example.

## Step 1: Add the workflow repository

Start from the Library page. If you have not added any catalogues yet, the page will be empty.

1. Click the **Actions** button in the top-left corner.
2. Select **Add Repository**.
3. Fill in the dialog:
   - **Name**: `raccoon-nf`
   - **Repository URL**: `https://github.com/artic-network/raccoon-nf`
   - **Version**: `latest`
4. Click **Add**.

GLACIER creates a **User collection** catalogue entry and adds a workflow card for raccoon-nf to the Library.

## Step 2: Install the workflow

The new raccoon-nf card shows an **Install** button. Click it.

GLACIER clones the repository from GitHub into your workflows directory. The button label changes to **Launch** once the clone completes.

## Step 3: Explore the parameters

Click the raccoon-nf card to open the **Parameters** page. Three tabs are available:

- **Info** — renders the workflow's `README.md`.
- **License** — shows the `LICENSE` file.
- **Params** — the configuration form generated from `nextflow_schema.json`.

Switch to the **Params** tab. You will see several collapsible sections:

| Section | Purpose |
|---------|---------|
| **Input Options** | Input FASTA file, metadata, sequence ID settings. |
| **Pipeline Options** | Alignment-only mode, masking, tree model, outgroup, threads. |
| **Sequence QC Options** | Minimum length, max N content, header templates. |
| **Alignment QC Options** | SNP flagging thresholds, clustering settings. |
| **Tree QC Options** | APOBEC/ADAR checks, long branch detection. |
| **Output Options** | Output directory name, figure height. |

The `fasta` field under **Input Options** is marked as required (with a red indicator). It must point to an input FASTA file for a normal run. For this tutorial we will use the **Test launch** button instead, which provides its own test data.

At the bottom of the page you will see a **Profiles** dropdown listing the available Nextflow profiles:

- `debug`, `standard`, `conda`, `mamba`, `docker`, `arm`, `singularity`, `podman`, `shifter`, `charliecloud`, `apptainer`, `wave`, `gpu`, `test`

Because the `test` profile exists, **Test launch** is available alongside the **Launch** button.

## Step 4: Launch with the test profile

Click **Test launch**. GLACIER will:

1. Select the `test` profile (combined with `standard` for Docker support).
2. Create a new instance with an auto-generated name (e.g. `brave-lion`).
3. Launch the pipeline using the bundled Nextflow and test data defined in `conf/test.config`.
4. Navigate to the **Monitor** page.

The `test` profile configures a minimal set of inputs:

```
fasta      = assets/test_data
metadata   = assets/test_data
min_length = 2000
tree_model = HKY+G
```

These are small files bundled in the raccoon-nf repository, so the pipeline completes quickly.

## Step 5: Monitor the run

On the Monitor page, watch the pipeline progress in real time.

### Progress tab

The **Progress** tab shows a tree of process groups (e.g. `RACCOON_NF:SEQ_QC`, `RACCOON_NF:ALIGNMENT`). Each process node has status icons (pending / submitted / completed / error) and a progress bar for multi-task processes.

Click the **⋮** menu on any completed process to inspect its log files — `.command.out`, `.command.err`, `.command.sh`, and more.

### Logs tab

Switch to the **Logs** tab for live-updating streams:

- **stdout** — Nextflow's standard output (refreshes every 1 second).
- **stderr** — Nextflow's standard error.
- **nextflow.log** — Nextflow's internal log file.

### Reports tab

When the pipeline finishes, the **Reports** tab may contain HTML output files generated by raccoon-nf (e.g. pipeline reports, tree visualisations).

### Run controls

Use the header buttons while the pipeline is running:

| Button | Action |
|--------|--------|
| **Cancel** | Graceful stop (SIGINT). |
| **Kill** | Force stop (SIGKILL). |
| **Resume** | Re-launch with `-resume` from the last checkpoint. |
| **Open Results Folder** | Open the instance directory in your file manager. |

## Step 6: View the completed instance

Switch to the **Instances** page (sidebar storage icon). The completed raccoon-nf run appears in the table with a green status icon. Click the icon to re-open the Monitor page and review outputs.

You can inspect the instance directory on disk at:

```
<documentsPath>/instances/artic-network/raccoon-nf@latest/<instance_name>/
```

This contains `params.json`, `stdout.log`, `stderr.log`, `nextflow.log`, the `work/` directory, and any reports.

## Summary

In this tutorial you:

1. Added a workflow repository via **Actions → Add Repository**.
2. Installed the workflow by clicking **Install**.
3. Explored the parameter form generated from `nextflow_schema.json`.
4. Launched the pipeline with **Test launch** using the `test` profile.
5. Monitored progress, logs, and reports on the Monitor page.
6. Located the completed instance in the Instances page and on disk.