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.

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

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

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

This command does the following:

  • -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.

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.

6. Access the environment through docker

To enter the Docker container and use the same environment as the app:

docker run -it --rm pauljonasjost/comicsart:latest bash

Then, inside the container:

R

If you want to have changed files save, e.g., during app development ensure to mount into the docker:

git clone  https://github.com/icb-dcm/cOmicsArt.git
cd cOmicsArt
docker run -it --rm \
  -v "$PWD":/workspace \
  -w /workspace \
  --name comicsart_dev \
  pauljonasjost/comicsart:latest bash

Note, for having an IDE and not just plain R a simple option is to use VS Code + Dev Containers:

  1. Start the container
  2. Open VS Code
  3. Install the Dev Containers extension
  4. Open the command palette
  5. Select: Dev Containers: Attach to Running Container…

This allows you to browse the file structure within the container, open a terminal inside it, and run R directly in the Docker environment.

Use the mounted local repository approach above, then open that local folder in VS Code to ensure local saved changes.

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.

…..

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