Rethinking Shiny Containerization: The shinydocker Experiment

Introduction

Containerization has become a cornerstone of modern application deployment, offering benefits like reproducibility, isolation, and streamlined deployments. However, the process of containerizing Shiny applications has traditionally required specialized knowledge of Docker, including writing Dockerfile & .dockerignore files, building images, and managing containers through command-line interfaces.

Enter {shinydocker} - an experimental R package designed to simplify this process through automation and intelligent defaults. In the new polyglot world, {shinydocker} provides a straightforward path to containerization without requiring deep Docker expertise for both R Shiny and Shiny for Python applications.

{shinydocker} is currently in the experimental/prototype stage. It is not yet available on CRAN and will likely undergo significant changes as we expand support for additional container runtimes.

Why Containerize Shiny Apps?

Before talking more about {shinydocker}, let’s briefly revisit why containerizing Shiny applications is valuable:

• Reproducibility: Containers package your app with its dependencies, ensuring consistent behavior across environments
• Isolation: Containers prevent dependency conflicts with other applications
• Ease of deployment: Containerized apps can be easily deployed to various platforms
• Scalability: Containers facilitate horizontal scaling of applications
• Version control: Container images can be versioned, allowing for controlled rollouts and rollbacks

These benefits are particularly relevant in the context of Shiny applications, which often rely on specific package versions and configurations. By containerizing your Shiny app, you can ensure that it runs consistently and reliably, regardless of the environment in which it is deployed.

Getting Started with shinydocker

{shinydocker} is designed to be user-friendly, even for those who may not be familiar with Docker. Though it is still in the a highly experimental stage, it provides a streamlined interface for containerizing Shiny applications.

Installation

You can install the development version of {shinydocker} from GitHub:

# install.packages("remotes")
remotes::install_github("coatless-rpkg/shinydocker")

Prerequisites

To use {shinydocker}, you need the following prerequisites:

• R (>= 4.4.0)
• Docker installed and running (no login required)
  • Optionally, Docker Compose for more advanced container management

{shinydocker} is currently in the experimental/prototype stage. The API and functionality may change significantly as we expand support for additional container runtimes.

One-Command Export: The Simplest Path

The quickest way to containerize a Shiny app is with the shinydocker::export() function, which handles the entire process in a single command:

library(shinydocker)

# Export and run an R or Python Shiny app (type is auto-detected)
shinydocker::export("path/to/your/shinyapp", run = TRUE)

This command:

1. Automatically detects whether your app is built with R or Python
2. Creates appropriate Docker configuration files
3. Builds a Docker image
4. Runs a container with your app
5. Provides a URL to access your running application

This design was inspired by the well-crafted shinylive interfaces for both Python and R, which similarly provide a streamlined experience with commands like shinylive export myapp site (in terminal) or shinylive::export() (in R). This approach prioritizes simplicity and user experience.

Example: Containerizing a Hello World App

Let’s see a concrete example of containerizing the classic “Hello World” Shiny app:

# Copy the Hello World example from the shiny package
app_dir <- "hello_world_app"
system.file("examples", "01_hello", package = "shiny") |>
  fs::dir_copy(app_dir, overwrite = TRUE)

# Export to Docker and run
shinydocker::export(app_dir, run = TRUE, detach = TRUE)

# The console will show a URL where you can access your containerized app

# Stop the container when done
shinydocker::stop_container()

Step-by-Step Approach

For more granular control, you can break down the process into individual steps:

library(shinydocker)

# 1. Create Docker configuration
shinydocker::dockerize("path/to/your/shinyapp")

# 2. Build Docker image 
shinydocker::build_image("path/to/your/shinyapp")

# 3. Run the container detached
shinydocker::run_container("path/to/your/shinyapp", detach = TRUE)

# 4. When done, stop the container
shinydocker::stop_container("path/to/your/shinyapp")

Workflow Overview

To better understand how {shinydocker} simplifies the containerization process, let’s visualize the traditional Docker workflow compared to the {shinydocker} approach:

flowchart TB

    A1[Write Dockerfile] --> B1[Configure .dockerignore]
    B1 --> C1[Write docker-compose.yml]
    C1 --> D1[Build Docker image]
    D1 --> E1[Run container]
    E1 --> G[Manage container lifecycle]
    
    A2{"Call export()"} -.->|Individually call| B2["Call dockerize()"]
    B2 --> C2["Call build_image()"]
    C2 --> D2["Call run_container()"]
    D2 --> G
    A2 -->|Automatic| G
        
    subgraph manualdocker["Traditional Docker Workflow"]
        A1
        B1
        C1
        D1
        E1
    end
    
    subgraph shinydocker["shinydocker Workflow"]
        A2
        B2
        C2
        D2
    end
    
    %% Node styles
    style A1 fill:#f8f9fa,stroke:#6c757d
    style B1 fill:#f8f9fa,stroke:#6c757d
    style C1 fill:#f8f9fa,stroke:#6c757d
    style D1 fill:#f8f9fa,stroke:#6c757d
    style E1 fill:#f8f9fa,stroke:#6c757d
    style G fill:#f8f9fa,stroke:#6c757d
    
    style A2 fill:#4582ec,stroke:#4582ec,color:#ffffff
    style B2 fill:#4582ec,stroke:#4582ec,color:#ffffff
    style C2 fill:#4582ec,stroke:#4582ec,color:#ffffff
    style D2 fill:#4582ec,stroke:#4582ec,color:#ffffff
    
    
    style shinydocker fill:#f8f9fa,stroke:#6c757d
    style manualdocker fill:#f8f9fa,stroke:#6c757d

Comparison of traditional Docker workflow vs. shinydocker

As the diagram illustrates, {shinydocker} handles a significant amount of complexity behind the scenes, from detecting the app type to scanning dependencies and configuring ports. Users can either use the one-step export() function or work through the individual steps with more granular control.

Intelligent App Type Detection

One of {shinydocker}’s key features is its ability to automatically detect whether your Shiny application is built with R or Python. This detection is based on the presence of key files:

• For R Shiny apps: app.R, server.R, or ui.R
• For Python Shiny apps: app.py, server.py, or ui.py

This allows you to use the same workflow regardless of which language your app is built with.

Automatic Dependency Detection

{shinydocker} also detects dependencies in your application:

• For R apps: Analyzes library/require calls and namespace references (package::function)
• For Python apps: Reads requirements.txt or analyzes import statements

This ensures your containerized application has all the required packages without manual specification.

Container Management

{shinydocker} includes comprehensive container management functions:

# Run container
shinydocker::run_container("path/to/your/shinyapp")

# Stop containers
shinydocker::stop_container("path/to/your/shinyapp")  # Specific app
shinydocker::stop_container()  # All containers

# Clean up
shinydocker::cleanup_container("path/to/your/shinyapp")  # Specific app
shinydocker::cleanup_container(remove_images = TRUE)  # All containers and images

Diagnostic Tools

The package provides tools to diagnose issues with your Docker environment or app containerization readiness:

# Check Docker environment setup
shinydocker::sitrep_docker()

# Check if your app is ready for containerization
shinydocker::sitrep_app_conversion("path/to/your/shinyapp")

These situation reports provide clear feedback on issues and recommendations for resolving them.

Under the Hood

{shinydocker} uses templates for generating Dockerfiles customized for R and Python Shiny applications. These templates incorporate best practices for containerizing each type of application.

For R Shiny apps, the package uses the rocker/shiny base image, which provides a pre-configured Shiny Server. For Python Shiny apps, it uses python:3.8-slim with the necessary libraries installed.

Future Directions

As indicated earlier, {shinydocker} is still in the experimental stage, and we have several exciting plans for its future. This means that the API and functionality may change significantly as we further work on this R&D package preview.

CI/CD Integration

The simple, one-command interface of {shinydocker} makes it ideal for integration with CI/CD workflows, such as GitHub Actions. This enables teams to automate the building and deployment of containerized Shiny applications as part of their development pipeline. For example, you could set up a workflow that automatically builds a new container image whenever changes are pushed to your repository.

Transition to dockitect for Templating

We plan to transition the templating system in {shinydocker} to leverage the recently introduced {dockitect} package. This specialized package provides more robust and flexible Docker template management, which will enhance our ability to generate optimal container configurations for different types of Shiny applications.

Container Runtime Abstraction

Currently, {shinydocker} focuses exclusively on Docker as the container runtime. However, the containerization landscape is evolving, with alternatives like Podman, containerd, and others gaining traction.

We’re planning to develop a new abstraction package (similar to how {DBI} provides a unified interface for database connections) that will allow {shinydocker} to work with multiple container runtimes. This will give users the flexibility to choose the runtime that best suits their needs while maintaining a consistent R interface.

This abstraction will:

1. Define a common interface for container operations
2. Allow plugins for different container runtimes
3. Maintain backward compatibility with existing {shinydocker} workflows
4. Provide runtime-specific optimizations when beneficial

As this work progresses, expect the {shinydocker} API to evolve!

Conclusion

{shinydocker} significantly lowers the barrier to containerizing Shiny applications, whether they’re built with R or Python. By automating Docker configuration, image building, and container management, it allows developers to focus on creating great Shiny apps rather than wrestling with containerization details.

Remember that {shinydocker} is still highly experimental, and we welcome feedback, bug reports, and feature requests through the GitHub repository.

Try It Out!

We encourage you to try {shinydocker} with your Shiny applications and share your experiences. To get started:

# install.packages("remotes")
remotes::install_github("coatless-rpkg/shinydocker")
library(shinydocker)

# Check your Docker setup
sitrep_docker()

# Try with an example app
export(system.file("examples", "shiny", "r", "hello-docker-plain", package = "shinydocker"), 
      run = TRUE)