# Docker Hands-on training (18-11-2026)

## Initial considerations
In this course, you can work on your laptop if you have installed the Docker in your machine. For local installation:

- Mac: <https://docs.docker.com/desktop/setup/install/mac-install/>
- Linux: <https://docs.docker.com/engine/install/>
- Windows: <https://docs.docker.com/desktop/setup/install/windows-install/>

Clone the repository that contain the data, script and all the course information
```
git clone git@github.com:biosustain/dsp_docker_training.git
```

Alternatively use Github Codespaces to avoid any system incompatibility. You can open directly a GitHub codespace for this specific repository here: [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/biosustain/dsp_docker_training)   

## Objective of this hands-on

Build a Docker image from a Dockerfile that contains [bowtie2](https://bowtie-bio.sourceforge.net/bowtie2/), [samtools](https://www.htslib.org/), [gffread](https://github.com/gpertea/gffread) and [Salmon](https://salmon.readthedocs.io/). Then run a script in a container from that image to align the reads of an *Escherichia coli* RNA-seq sample with bowtie2 and quantify the reads per transcript and per gene with Salmon, in the same way as the `bowtie2_salmon` mode of [nf-core/rnaseq](https://nf-co.re/rnaseq/3.23.0) for prokaryotes. The input data stays on your machine and the results come back to it.

## What we are going to do

![Hands-on workflow: pull a Debian base image, write a Dockerfile with bowtie2, samtools, gffread and Salmon, build the image, and run a container that mounts data/ read-only and results/ read-write to build the bowtie2 index, align and sort, index the BAM and count reads with Salmon](images/HandsOn_20261118_workflow.svg)

1. Pull the latest Debian image from Docker Hub.
2. Write a Dockerfile that adds bowtie2, samtools, gffread, Salmon and our script on top of Debian.
3. Build the Docker image from the Dockerfile.
4. Run a container from that image. It mounts `data/` read-only and `results/` read-write, and runs the script that:
    1. generates the bowtie2 index,
    2. aligns the reads with bowtie2 and sorts the BAM file,
    3. indexes the sorted BAM file,
    4. counts the reads per transcript and per gene with Salmon.
5. Look at the results in `results/` on your machine.

## Running a container

First of all, if you installed Docker Desktop on your machine check that Docker Desktop is open and shows “Running” in the status bar.

You can also test with:
```
docker -v
```  
```
docker info
```

Once the docker daemon is running you can create and run a new container from an image, we will start with the `hello-world` image, which is hosted on [Docker Hub](https://hub.docker.com/).

>Docker Hub is Docker’s public registry service where we can store, share, and manage container images. 
>It hosts Docker Official Images (like hello-world), Verified Publisher content, and community-contributed images.

In your command line, run the publicly available `hello-world` image:
```
docker run hello-world
```
We usually run that to check that our installation is working correctly. If you read `'Hello from Docker!'` everything is fine for now.

Please read the information given to understand what happened. 

What happens:

1. Client (your terminal) sends run hello-world request.

2. Daemon (the engine) checks if image exists; if not, pulls it.

3. Daemon creates and runs the container (i.e hello-world).

4. Output is sent back to the client ("Hello from Docker!").

## Pulling a container

Pull the latest publicly available debian image: `debian:latest` and verify it has been downloaded. Images are pulled by default from [Docker hub](https://hub.docker.com/).
```
docker pull debian:latest
```
In Docker image names like `debian:latest`, the colon separates the image name from its tag.
> `latest` is the tag Docker uses when no tag is given (`docker pull debian` is the same as `docker pull debian:latest`). 
> For the Debian image it points to the current stable release: Debian 13 "Trixie".
> `latest` moves to a new version over time, so it is handy for exploring but not for reproducible pipelines.

Check which Debian version you got:
```
docker run --rm debian:latest cat /etc/debian_version
```
If you wondered, adding --rm to the run command is to make sure the container is wiped after usage.

To check which images you have pulled, you can use `images` command with the following syntax:
```
docker images
``` 

## Writing our Dockerfile

Docker images are created from a textfile called `Dockerfile`. 

This text file contains list of commands to assemble and configure the image with the software required.

For our dockerfile, we will learn the following instructions: `FROM`, `LABEL`, `WORKDIR`, `RUN` and `COPY`
Go to [Dockerfile references](https://docs.docker.com/reference/dockerfile/) and find out what are these instructions for.

First thing we need is a base image. A dockerfile can use an existing image, and build on top of it. A base image is an image you designate with `FROM` directive in a Dockerfile. A Dockerfile with the `FROM scratch` directive uses an empty base image. When we build the Docker image from `debian:13` we will get an image with something really close to having installed debian distribution (version 13). 

What do we need to add to our Dockerfile?
- Base image
- Metadata about the image
- Working directory
- Instructions to download and install software
    - bowtie2: align reads to a reference
    - samtools: deal with .bam files (sorting and indexing them)
    - gffread: build the transcript sequences from the genome and the annotation (GTF)
    - salmon: quantify reads per transcript and per gene
- copy the scripts folder

Open a file called Dockerfile:  
```
code docker_file/Dockerfile
```

First let's specify which base image we want to use. We just pulled `debian:latest`, which today is Debian 13. In the Dockerfile we write the version number instead of `latest`, so the image is built on the same Debian release even when `latest` moves to a newer one:
```{code-block} docker
# Adding a base image
FROM debian:13
```

Add some metadata to the image with `LABEL`:
```{code-block} docker
# Adding some metadata to the image
LABEL image.description="A docker image for aligning prokaryotic RNA-seq data with bowtie2 and quantifying reads with Salmon"
LABEL image.author.name="Your name"
LABEL image.author.email="your.email@example.com"
```

Define the working directory:
```{code-block} docker
# Setting the working directory
WORKDIR /app
```

Next, we are going to update the package manager `apt-get` (included in the debian image) and install the software that we need. All four tools are available in `apt-get`, which is the easiest solution. We need to use `RUN` to execute building commands. `apt-get update` downloads the package lists from the Debian servers into /var/lib/apt/lists/. That catalogue is needed to find and install packages, but once they’re installed it’s no longer needed. Removing the `apt-get` package lists at the end of the same `RUN` keeps the image smaller.
```{code-block} docker
# Installing required software from apt-get
# bowtie2: align reads to a reference
# samtools: deal with .bam files (sorting and indexing them)
# gffread: build the transcriptome fasta from the genome and the GTF
# salmon: count reads per transcript and per gene
RUN apt-get update && apt-get -y install \
    bowtie2 \
    gffread \
    salmon \
    samtools && \
    rm -rf /var/lib/apt/lists/*
``` 

> In the previous edition of this course we used featureCounts, which is not in `apt-get`. We had to download it with `curl`, uncompress it and add it to the `PATH` with `ENV`. 
> Always check first if your software is in `apt-get` (or another package manager): it makes the Dockerfile shorter and easier to maintain.

Finally we are going to copy to the image the scripts folder that contains the script that we are going to run.
```{code-block} docker
# Copy the scripts folder to the image
COPY scripts/ ./scripts/
```

## Building an image from the Dockerfile

When you have a Dockerfile, you can build it to a docker image with the `build` command using the following syntax:
`docker build --tag <my-image-name:my-optional-image-tag> <my-location-path>`, where `--tag` is equivalent to `-t`, `-f` specifies the Dockerfile, and last thing is `<my-location-path>` that can be referenced with `.`

Let's build your Dockerfile to an image:

```{code-block} bash
docker build -t align_count -f docker_file/Dockerfile .
```

If in doubt for whatever reason of your Dockerfile, the complete Dockerfile prepared by us is in [docker_file/Dockerfile_salmon](https://github.com/biosustain/dsp_docker_training/blob/main/docker_file/Dockerfile_salmon). If you use this one change the command accordingly:

```{code-block} bash
docker build -t align_count -f docker_file/Dockerfile_salmon .
```

Check now which images do you have locally?
```
docker images
```

## Running a container in interactive mode

While we would rather recommend using _virtual environments_ for running specific environments interactively, it can be handy to be familiar with docker's ability to run a container in interactive mode. This is just useful to check if the expected software is present within a container, but we do not recommend to change anything in the container, instead do it in the Dockerfile.

The interactive mode is achieved by adding two command line inputs to the `docker run` command: `--interactive` and `--tty`,  which have the equivalents `-i` and `-t`. `-i` lets you type into the container, and `-t` makes it behave like a terminal. Together they give you an interactive shell.

Remember you can always run the following to find out what the parameters used in `docker run` are:
```
docker run --help
```
The interactive mode can be run with the following syntax: `docker run -it <image-name> <command>`

We will launch the BASH shell (`bash`) in the `align_count` image:
```{code-block} bash
docker run -it align_count bash
```
Then you can check what is in there `ls -la` or in which directory are we `pwd`. Which folder can you see?

After looking around lets exit the bash with `exit`.

Check which software versions you included in your Docker image:
```
docker run align_count bowtie2 --version
```
```
docker run align_count samtools --version
```
```
docker run align_count gffread --version
```
```
docker run align_count salmon --version
```

We know that our images are locally available. We also want to check if our containers are still existing.

To do this try: 
```
docker ps -a
``` 

The `CONTAINER ID` and `NAMES` columns identify each container. The `STATUS` column shows whether it is still running (Up ...) or stopped (Exited ...). We can see that they are stopped but still existing. There is no reason for this as these containers are supposed to just do one job based on the docker image.

To remove specific containers, by ID or name:

```{code-block} bash
docker rm <container-id-or-name>
```

And to remove all stopped ones at once:
```{code-block} bash
docker container prune
```

We can keep our space tidy by adding `--rm` to the run command to make sure the container is wiped after usage.

## File system mounts

Containers are isolated and run in a completely separate file system and it cannot access the hosting file system by default.

We can use the `--volume <host-directory>:<container-directory>` syntax to make a file or a folder available inside our container. `-v` is equivalent to `--volume`. Its argument consists of two fields separated by a colon (`:`):

- Host source directory path
- Container target directory path

In Docker, there is no fixed hard limit on how many -v (volume mounts) you can attach to a container.

## Running the container mounting the data

Finally we are going to build our command line to run our script to align and count the reads inside the Docker container.

We will now make two mounted volumes, a read-only for data (ro), and a writable one for results

Mount paths must be absolute on the container side.

```{code-block} bash
docker run --rm -v ./data/:/app/data:ro -v ./results/:/app/results align_count ./scripts/align_and_count_nfcore_rnaseq_prok_mode.sh
```

The script runs these steps (see the [shell script](align_and_count_nfcore_rnaseq_prok_mode_shell_script.md)):

- **Step 0: Prepare the transcript sequences.** Salmon counts reads per transcript, so bowtie2 aligns the reads to the transcript sequences instead of to the whole genome. gffread builds these sequences from the genome and the GTF, after removing the GTF lines with an empty `transcript_id ""` that NCBI files for bacteria contain.
- **Step 1:** Generate bowtie index (only required once).
- **Step 2:** Run bowtie2 alignment and sort the output BAM file.
- **Step 3:** Index the sorted BAM file: enables fast random access to specific regions of the data.
- **Step 4:** Run Salmon to count reads per transcript and gene.

## Results files and interpretation

Results have been copied back from the container to my local ```results``` folder (host). Let's have a look.  

The main output files are:  

- Running ```bowtie2```/```samtools``` generates:
    - ```aligned.bam```: the alignments in the order bowtie2 wrote them. Salmon reads this file.
    - ```aligned_sorted.bam``` and its index ```aligned_sorted.bam.bai```: the alignments sorted by position, for example to look at them in a genome browser.
    - The bowtie2 summary printed on the screen shows that about 64% of the 50000 read pairs aligned.
- Running ```salmon``` generates the ```salmon_quant``` folder:
    - ```quant.sf```: estimated read counts per transcript. The `NumReads` column holds the estimated number of reads.
    - ```quant.genes.sf```: the same values summarised per gene. Out of 4511 genes, 2426 genes have an estimated read count of at least 1.
    - Counts are *estimates*, so `NumReads` can have decimals (Salmon shares out reads that match more than one transcript, and those shares are usually fractions)
    - ```logs/salmon_quant.log```: the full Salmon log. Look for the `Total # of mapped reads` line: 31921 read pairs were counted.
