Local Installation

A comic about a cat finding cOmicsART Image generated using DALL-E by OpenAI. Adjusted by Lea Seep

Why do you want to install cOmicsART locally? If you just want to use it make sure to check out the website: cOmicsART. Here is no installation effort required. If you know you are right here, let’s get started. You can find here instructions to run cOmicsART locally within RStudio or using Docker.

Running a cOmicsART locally within RStudio

This guide provides detailed instructions on how to install and run the Shiny app from the provided GitHub repository.

Prerequisites

Ensure you have the following software installed on your system: - Git - R - RStudio - renv package in R.

Note: cOmicsArt is built on version 4.2.0 of R. To run cOmicsArt locally, please make sure you have version 4.2.0 installed.
For Windows users: In addition to the above mentioned software, [Rtools42](https://cran.r-project.org/bin/windows/Rtools/rtools42/rtools.html) is required to build pacakges from source.

Steps to Install and Run the Shiny App

1. Clone the GitHub Repository

Open a terminal or command prompt and use the following command to clone the repository:

git clone https://github.com/icb-dcm/cOmicsArt.git

2. Navigate to the Project Directory

Change the directory to the cloned repository:

cd cOmicsArt

3. Restore the R Environment

The project uses renv to manage dependencies. Restore the required R packages using the renv.lock file. Open R or RStudio. Ensure the package renv is installed in your R environment.Test with

library(renv)

If you get an error, install it using the following command:

install.packages("renv")

Then set the working directory to the root directory to install the environment from the lock file:

renv::restore(lockfile="renv.lock")

This will install all the necessary packages as specified in the renv.lock file. Note: This takes quite some time as there are a lot of packages to retrieve. Some of those need specific system dependencies. Also note that you can use R within the provided Docker image, which comes with a fully preloaded and ready-to-use environment. See #Running a cOmicsART Using Docker.

4. Start the Shiny App

From the R console, start the Shiny app using the following command. Note that you will need to be in the program directory.

shiny::runApp('shinyApp',port=3939)

After starting the Shiny app, you will see an IP address printed in the R console:

Listening on http://127.0.0.1:3939

Open your web browser and go to the provided IP address to access the Shiny app.

Running a cOmicsART Using Docker

This guide will help you use the provided Docker image to start your Shiny app.

Prerequisites

1. Install Docker

Ensure Docker is installed on your system. You can download and install Docker from Docker’s official website.

Apple Silicon (M1/M2/M3) users: The image is built for the linux/amd64 architecture and runs under emulation on Apple Silicon. App mode works out of the box. For the development (RStudio) mode you must enable Apple's Virtualization framework and Rosetta in Docker Desktop, otherwise RStudio will show "Unable to connect to service":

Docker Desktop → Settings → General → set Virtual Machine Manager (VMM) to Apple Virtualization framework → tick "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" → Apply & Restart. Requires macOS 13 (Ventura) or newer.

Steps to Install and Run the Shiny App

2. Pull the Docker Image

Open a terminal or command prompt and use the following command to pull the Docker image from Docker Hub:

docker pull pauljonasjost/comicsart:latest

3. Run the Docker Container (App mode)

After pulling the image, you can run the Docker container with the following command:

docker run --rm -p 3838:3838 pauljonasjost/comicsart:latest

This command does the following:

  • --rm removes the container automatically when you stop it.
  • -p 3838:3838 maps port 3838 in the Docker container to port 3838 on your local machine.
  • pauljonasjost/comicsart:latest specifies the Docker image to run.

The image supports two modes, selected with the MODE environment variable: MODE=app (the default, shown above) runs the Shiny app, and MODE=rstudio starts an RStudio Server for development (see Development mode (RStudio) below). Because app is the default, no -e MODE=... flag is needed to run the app.

4. Access the Shiny App

Once the container is running, open your web browser and navigate to:

http://localhost:3838

This will open the Shiny app in your browser. Note, that this intitially may take some time due to initializing.

5. Update the Docker Image

To update the Docker image with the latest version, pull the image again:

docker pull pauljonasjost/comicsart:latest

Then follow the steps to run the updated image.

Development mode (RStudio)

The same image can start an RStudio Server, giving you the app’s fully preloaded R environment inside a browser-based IDE. This is the recommended way to develop or debug the app without setting up renv locally.

Apple Silicon: development mode requires the Apple Virtualization framework + Rosetta to be enabled first — see the note under Install Docker.

Clone the repository (so your edits are saved to your machine), then start the container in rstudio mode with your local program/ folder mounted into it:

git clone https://github.com/icb-dcm/cOmicsArt.git
cd cOmicsArt

docker run --rm -p 8787:8787 \
  -e MODE=rstudio \
  -e PASSWORD=yourpassword \
  -v "$PWD/program":/home/rstudio/project \
  pauljonasjost/comicsart:latest

This does the following:

  • -p 8787:8787 maps RStudio Server’s port to your machine.
  • -e MODE=rstudio starts RStudio Server instead of the app.
  • -e PASSWORD=yourpassword sets the login password (choose your own).
  • -v "$PWD/program":/home/rstudio/project mounts your local program/ folder into the container at ~/project, so any changes you make are written back to your machine.

Then open http://localhost:8787 and log in with username rstudio and the password you set. Your mounted code is in the project/ folder. To launch the app from within RStudio:

shiny::runApp("project/shinyApp")

Because the environment is baked into the image, packages such as DESeq2 and ggtree load immediately — no renv::restore() needed.

Adding a new R package

The R environment is tracked in program/renv.lock, and the Docker image is rebuilt from it automatically (see the image-build workflow). The image is set up so the rstudio user can install packages directly and renv can record them. (note no renv::init() or restore required. From development mode above, in the RStudio Console:

  1. Install the package:

    lib <- path.expand("~/R/dev-library"); dir.create(lib, recursive = TRUE, showWarnings = FALSE)
.libPaths(c(lib, .libPaths()))
Sys.setenv(RENV_PATHS_CACHE = path.expand("~/.cache/R/renv"))
# Then install your package, e.g.:
# install.packages("e1071")            # a CRAN package
# for a Bioconductor package instead: BiocManager::install("somePkg")
# library(e1071)                        # quick check it loads

  2. Record it — and its dependencies — into the lockfile:

    renv::snapshot(project  = "~/project",
               lockfile = "~/project/renv.lock",
               type     = "all",
               exclude  = c("renv", "BiocManager"))

  3. Back on your machine, review and commit the lockfile change:

    git diff program/renv.lock            # should add your package (+ its deps)
git add program/renv.lock
git commit -m "Add e1071"
git push

On push, the image is rebuilt from the updated renv.lock and the startup test runs against it. Afterwards, docker pull the refreshed image to use the new package in the container.

Alternative: plain shell / VS Code Dev Containers If you prefer a terminal or VS Code instead of RStudio, you can open a shell in the same environment: ```bash docker run -it --rm \ -v "$PWD":/workspace \ -w /workspace \ --name comicsart_dev \ pauljonasjost/comicsart:latest bash ``` For an IDE, use VS Code + the **Dev Containers** extension: start the container, then in VS Code open the command palette and select *Dev Containers: Attach to Running Container...*. Open your mounted local folder so saved changes persist on your machine.

Troubleshooting

If you encounter issues, consider the following tips:

  • Port Conflicts: If port 3838 is already in use, map the container’s port to a different local port, e.g., 8888:

    docker run -p 8888:3838 username/shinyapp:latest

    Then access the app at http://localhost:8888.

  • Permissions Issues: On Linux, you may need to use sudo for Docker commands.

  • RStudio “Unable to connect to service” (Apple Silicon): Development mode needs Docker Desktop’s Apple Virtualization framework + Rosetta enabled (Settings → General → VMM: Apple Virtualization framework → Use Rosetta for x86_64/amd64 emulation). App mode is unaffected.

…..

This site uses Just the Docs, a documentation theme for Jekyll.