---
title: "SPR Docker container"
author: "Author: Daniela Cassol (danielac@ucr.edu)"
date: "Last update: `r format(Sys.time(), '%d %B, %Y')`"
output:
BiocStyle::html_document:
toc_float: true
code_folding: show
BiocStyle::pdf_document: default
package: systemPipeR
fontsize: 14pt
type: docs
weight: 4
---
> Guidelines from [bioconductor_docker](https://github.com/Bioconductor/bioconductor_docker).
## Running the `systemPipeR` with Docker
### Get a copy of the public docker image
```{bash, eval=FALSE}
docker pull systempipe/systempipe_docker:latest
```
### To run RStudio Server:
```{bash, eval=FALSE}
docker run -e PASSWORD=systemPipe -p 8787:8787 \
systempipe/systempipe_docker:latest
```
You can then open a web browser pointing to your docker host on
port 8787. If you're on Linux and using default settings, the docker
host is `127.0.0.1` (or `localhost`, so the full URL to RStudio would
be `http://localhost:8787)`. If you are on Mac or Windows and running
`Docker Toolbox`, you can determine the docker host with the
`docker-machine ip default` command.
In the above command, `-e PASSWORD=` is setting the RStudio password
and is required by the RStudio Docker image. It can be whatever you
like except it cannot be `rstudio`. Log in to RStudio with the
username `rstudio` and whatever password was specified, in this
example `systemPipe`.
### To run R from the command line:
```{bash, eval=FALSE}
docker run -it --user rstudio systempipe/systempipe_docker:latest R
```
### To open a Bash shell on the container:
```{bash, eval=FALSE}
docker run -it --user rstudio systempipe/systempipe_docker:latest bash
```
* * *
## Install
**Prerequisites**:
[Linux](https://docs.docker.com/installation/)
[Mac](http://docs.docker.com/installation/mac/)
[Windows](http://docs.docker.com/installation/windows/)
Instructions [here](https://docs.docker.com/engine/install/ubuntu/) on how to install Docker Engine on Ubuntu.
```{bash, eval=FALSE}
sudo apt-get update
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo \
"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
## Verify that Docker Engine is installed correctly by running the hello-world image.
sudo docker run hello-world
```
### Uninstall
```{bash, eval=FALSE}
sudo apt-get remove docker docker-engine docker.io containerd runc
```
* * *
## Docker Hub Account
To be able to share a custom image, please go to https://hub.docker.com and
create a free account.
* * *
### Log in to the Docker Hub locally
Login with your Docker ID to push and pull images from Docker Hub. If you don't
have a Docker ID, head over to https://hub.docker.com to create one.
```{bash, eval=FALSE}
docker login
# Username: XXXX
# Password: xxx
# Login Succeeded
```
* * *
## Run Docker
```{bash, eval=FALSE}
docker run-dP systempipe/systempipe_docker:latest
```
Make sure the container is running:
```{bash, eval=FALSE}
docker ps
# CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS # NAMES
#5d007f66a7b3 systempipe/systempipe_docker:latest "/init" 5 minutes ago Up 5 minutes 0.0.0.0:49153->8787/tcp determined_easle
```
### Login to the container
Please check the `NAMES` in this example, `determined_easle,` to login into the container.
```{bash, eval=FALSE}
docker exec -it determined_easle /bin/bash
```
## Other alternatives to run the container
#### To run RStudio Server:
```{bash, eval=FALSE}
docker run -e PASSWORD=systemPipe -p 8787:8787 \
systempipe/systempipe_docker:latest
```
#### To run R from the command line:
```{bash, eval=FALSE}
docker run -it --user rstudio systempipe/systempipe_docker:latest R
```
#### To open a Bash shell on the container:
```{bash, eval=FALSE}
docker run -it --user rstudio systempipe/systempipe_docker:latest bash
```
#### Check R Version into the container
```{bash, eval=FALSE}
R --version
```
### Stop Docker
```{bash, eval=FALSE}
docker stop determined_easle
```
* * *
## Create your first repository [Link](https://docs.docker.com/docker-hub/)
### Create a repository:
- Sign in to Docker Hub.
- Click Create a Repository on the Docker Hub welcome page:
- Name it /my-repo.
- Click Create.
### Build and push a container image to Docker Hub from your computer
#### Start by creating a *Dockerfile* to specify your application
```{bash, eval=FALSE}
mkdir docker_test
cd docker_test
touch Dockerfile
```
```{bash, eval=FALSE}
# Docker inheritance
FROM systempipe/systempipe_docker:latest
## Install BiocStyle
RUN R -e 'BiocManager::install("BiocStyle")'
# Install required Bioconductor package from devel version
RUN R -e 'BiocManager::install("tgirke/systemPipeR")'
RUN R -e 'BiocManager::install("tgirke/systemPipeRdata")'
WORKDIR /home/rstudio/SPRojects
COPY --chown=rstudio:rstudio . /home/rstudio/SPRojects
# Metadata
LABEL name="systempipe/systempipe_docker" \
version=$BIOCONDUCTOR_DOCKER_systempipe \
url="https://github.com/systemPipeR/systempipe/systempipe_docker" \
vendor="systemPipeR Project" \
maintainer="email@gmail.com" \
description="Bioconductor docker image containing the systemPipeR Project" \
license="Artistic-2.0"
```
#### Run `docker build` to build your Docker image
```{bash, eval=FALSE}
docker build -t systempipe/systempipe_docker .
```
#### Run `docker run` to test your Docker image locally
```{bash, eval=FALSE}
docker run -e PASSWORD=systemPipe -p 8787:8787 systempipe/systempipe_docker:latest
```
#### Run `docker push` to push your Docker image to Docker Hub
```{bash, eval=FALSE}
docker push systempipe/systempipe_docker
```
- Your repository in Docker Hub should now display a new latest tag under `Tags`
* * *
## Make changes to the container and Create the new image
Create a folder, for example:
```{bash, eval=FALSE}
docker run -dP systempipe/systempipe_docker
docker ps ## To check the NAME
docker exec -it lucid_grothendieck /bin/bash
root@33c758eb1626:/# R
```
```{bash, eval=FALSE}
setwd("home/rstudio/")
systemPipeRdata::genWorkenvir("rnaseq")
```
```{bash, eval=FALSE}
exit
docker commit -m "Added rnaseq template" -a "Dani Cassol" lucid_grothendieck dcassol/systempipeworkshop2021:rnaseq
docker push systempipe/systempipe_docker:rnaseq
```
Run the new image:
```{bash, eval=FALSE}
docker run -e PASSWORD=systemPipe -p 8787:8787 systempipe/systempipe_docker:rnaseq
```
* * *
## Commands
### List which docker machines are available locally
```{bash, eval=FALSE}docker images```
### List running containers
```{bash, eval=FALSE}docker ps```
### List all containers
```{bash, eval=FALSE}docker ps -a```
### Resume a stopped container
```{bash, eval=FALSE}docker start ```
### Shell into a running container
```{bash, eval=FALSE}docker exec -it /bin/bash```
### Stop OR remove a cointainer
```{bash, eval=FALSE}docker stop ```
```{bash, eval=FALSE}docker rm ```
### Remove a image
```{bash, eval=FALSE}docker rmi dcassol/systempipeworkshop2021:rnaseq```
* * *
## Docker and GitHub Actions
1. To create a new token, go to Docker Hub Settings
1.1. Account Settings >> Security >> New Access Token
1.2. Add Access Token Description >> Create
1.3. Copy the Access Token >> Copy and Close
2. Go to the Repository at GitHub
2.1. Settings > Secrets > New repository secret
2.2. Create a new secret with the name `DOCKER_HUB_USERNAME` and your `Docker ID` as value
2.3. Click at Add secret
2.4. Create a new secret with the name `DOCKER_HUB_ACCESS_TOKEN` and your `Personal Access Token (PAT)` as value (generated in the previous step)
3. Set up the GitHub Actions workflow
```{bash, eval=FALSE}
steps:
- name: Checkout Repo
uses: actions/checkout@v2
- name: Login to Docker Hub
uses: docker/login-action@v1
with:
username: ${{ secrets.DOCKER_HUB_USERNAME }}
password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
```
* * *
## Common Problems
```{bash, eval=FALSE}
## Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post http://%2Fvar%2Frun%2Fdocker.sock/v1.24/auth: dial unix /var/run/docker.sock: connect: permission denied
```
Solution:
```{bash, eval=FALSE}
sudo chmod 666 /var/run/docker.sock
```
* * *
## Singularity Container
Please download the Docker image of systemPipe, as follow:
```{bash, eval=FALSE}
singularity pull docker://systempipe/systempipe_docker:latest
```
You can also use the `build` command to download pre-built images from Docker.
Unlike `pull`, `build` will convert the image to the latest Singularity image format after
downloading it.
```{bash, eval=FALSE}
singularity build systempipe_docker_latest.sif docker://systempipe/systempipe_docker:latest
```
To run the container:
```{bash, eval=FALSE}
singularity shell systempipe_docker_latest.sif
```
* * *
## Resources
- [Docker Run: How to create images from an application](https://www.mirantis.com/blog/how-do-i-create-a-new-docker-image-for-my-application/)
- [Docker Hub Quickstart](https://docs.docker.com/docker-hub/)
- [Configure GitHub Actions](https://docs.docker.com/ci-cd/github-actions/)
- [Singularity](https://sylabs.io/guides/3.0/user-guide/quick_start.html#interact-with-images)