bhagesh/bioworkspace repository overview

⁠Root Bioinformatics IDE Container

A root-operated Docker development environment for bioinformatics work. One container provides:

• R and RStudio Server at port 8787
• Python and JupyterLab at port 8888
• Browser-based VS Code through code-server at port 8080
• Persistent host folders for projects, data, R packages, Python packages, Jupyter configuration, and VS Code configuration

This setup is intended for a trusted local development machine. All interactive sessions run as root in the container. You do not need sudo, su, or pip install --user when installing software in the container.

⁠Project links

• Source code and Dockerfile: github.com/bhagesh-h/bioworkspace⁠
• Prebuilt Docker image: hub.docker.com/r/bhagesh/bioworkspace⁠

⁠Important security note

Running IDEs as root is convenient for a single-user local research environment, but it is not appropriate to expose directly to a network or the internet. The run command in this README binds all services to 127.0.0.1, so they are reachable only from the same computer.

Use strong, unique values for PASSWORD and JUPYTER_TOKEN. Do not replace 127.0.0.1 with 0.0.0.0 unless you first add suitable TLS and network-level access controls.

⁠Requirements

• Docker Desktop on Windows/macOS, or Docker Engine on Linux
• Docker Compose is optional; this README uses plain docker commands
• The Dockerfile is available in this repository as Dockerfile

Verify Docker is available:

docker version

⁠Get the image

⁠Pull from Docker Hub

The quickest way to start is to pull the published image:

docker pull bhagesh/bioworkspace:latest

Confirm it is available locally:

docker image ls bhagesh/bioworkspace

⁠Build from source

Clone the repository if you want to inspect or modify the Dockerfile:

git clone https://github.com/bhagesh-h/bioworkspace.git
cd bioworkspace

Build a local image with the same Docker Hub image name:

docker build \
  -f Dockerfile \
  -t bioworkspace \
  .

The first build downloads the Rocker base image, code-server, micromamba, Python, and JupyterLab. Later builds use Docker's cache unless you change an earlier Dockerfile layer.

⁠Directory layout

Create persistent host folders. Run this from the directory where you want your projects and package libraries stored:

mkdir -p workspace data r-library python-packages jupyter-config code-config

Do not mount a host directory on /bin, /usr/bin, /opt/jupyter/bin, or /opt/jupyter. Those locations contain executables supplied by the base image, and a bind mount would hide them.

⁠Start the container

Run this command from the directory containing workspace/, data/, and the other persistent folders:

docker run --rm -it \
  --name bioworkspace \
  -p 127.0.0.1:8787:8787 \
  -p 127.0.0.1:8080:8080 \
  -p 127.0.0.1:8888:8888 \
  -e PASSWORD='replace-with-a-strong-password' \
  -e JUPYTER_TOKEN='replace-with-a-separate-strong-token' \
  --mount type=bind,src="$(pwd)/workspace",dst=/workspace \
  --mount type=bind,src="$(pwd)/data",dst=/data \
  --mount type=bind,src="$(pwd)/r-library",dst=/opt/R/library \
  --mount type=bind,src="$(pwd)/python-packages",dst=/opt/python \
  --mount type=bind,src="$(pwd)/jupyter-config",dst=/root/.jupyter \
  --mount type=bind,src="$(pwd)/code-config",dst=/root/.config/code-server \
  bhagesh/bioworkspace:latest

⁠Windows PowerShell

Use ${PWD} rather than $(pwd) if needed:

docker run --rm -it `
  --name bioworkspace `
  -p 127.0.0.1:8787:8787 `
  -p 127.0.0.1:8080:8080 `
  -p 127.0.0.1:8888:8888 `
  -e PASSWORD='replace-with-a-strong-password' `
  -e JUPYTER_TOKEN='replace-with-a-separate-strong-token' `
  --mount type=bind,src="${PWD}/workspace",dst=/workspace `
  --mount type=bind,src="${PWD}/data",dst=/data `
  --mount type=bind,src="${PWD}/r-library",dst=/opt/R/library `
  --mount type=bind,src="${PWD}/python-packages",dst=/opt/python `
  --mount type=bind,src="${PWD}/jupyter-config",dst=/root/.jupyter `
  --mount type=bind,src="${PWD}/code-config",dst=/root/.config/code-server `
  bhagesh/bioworkspace:latest

The terminal running this command shows service logs. Stop the container with Ctrl+C. Because --rm is used, the container itself is deleted when it stops; the mounted host directories remain intact.

⁠Open the IDEs

JupyterLab opens files from /workspace. In RStudio and code-server, open /workspace as the working project folder. Input data is available at /data.

⁠Install software

All terminals and notebook kernels run as root. Use ordinary installation commands.

⁠Python packages

Run these from a JupyterLab terminal, code-server terminal, RStudio terminal, or docker exec shell:

pip install scanpy anndata muon pandas pyarrow
pip install biopython pysam pybedtools

The image configures pip to install into /opt/python. Since that directory is bind-mounted to python-packages/, installed packages and executable tools persist on the host. Do not add --user.

python -c "import scanpy; print(scanpy.__file__)"

⁠R and Bioconductor packages

In RStudio, an R notebook, or an R terminal:

install.packages("data.table", repos = "https://cloud.r-project.org")
install.packages(c("ggplot2", "tidyverse"), repos = "https://cloud.r-project.org")

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager", repos = "https://cloud.r-project.org")
}
BiocManager::install(c("DESeq2", "SingleCellExperiment", "GenomicRanges"))

R_LIBS_USER=/opt/R/library makes these packages persist in r-library/.

⁠Linux and bioinformatics tools

Install OS packages without sudo:

apt-get update
apt-get install -y samtools bedtools bcftools tabix

Packages installed with apt-get modify the running container only and disappear when it is removed. For reproducibility, add frequently used OS packages to the Dockerfile's apt-get install block, then rebuild the image.

⁠Use persistent data safely

The default data/ mount is read/write. If it contains raw sequencing data or reference files that should not be modified, mount it read-only:

--mount type=bind,src="$(pwd)/data",dst=/data,readonly

Write derived files to /workspace/results, which maps to local workspace/results:

mkdir -p /workspace/results
samtools flagstat /data/sample.bam > /workspace/results/sample.flagstat.txt

⁠Enter a running container

Open a root shell in the running container:

docker exec -it bioworkspace bash

Useful checks:

whoami
python --version
R --version
jupyter lab path

whoami should return root.

⁠JupyterLab asset error

Do not set JUPYTERLAB_DIR in this image. It overrides JupyterLab's installed application directory. If it points to an empty mounted directory, JupyterLab fails with JupyterLab application assets not found.

The application assets supplied by the micromamba environment remain at /opt/jupyter/share/jupyter/lab. Persist user configuration by mounting /root/.jupyter, as shown above, rather than overriding the application directory.

⁠Stop, restart, and clean up

Press Ctrl+C to stop a foreground container, then run the same docker run command to restart it. Work, data, installed R/Python packages, and IDE configuration remain in the local bind-mounted folders.

For a detached container, stop it with:

docker stop bioworkspace

List Docker resources:

docker ps -a
docker image ls

Remove the local image if no longer needed:

docker image rm bhagesh/bioworkspace:latest

This does not remove workspace/, data/, or any other local persistent folders.