Skip to contents

Docker Deployment

Source: vignettes/docker-deployment.qmd

This guide provides complete instructions for building, deploying, and using the artaverse Docker container with the full Artalytics platform pre-installed.

Overview

The artaverse Docker image provides:

  • Complete R environment (R 4.4.2 with development tools)
  • All 18 Artalytics packages installed and ready
  • ~180 dependencies including ImageMagick, FFmpeg, tesseract
  • Bash entry point for maximum flexibility
  • Auto-loading artaverse in interactive R sessions

Image size: ~2.5GB Build time: ~15-20 minutes (first build)

Prerequisites

1. Install Docker

macOS:

# Install Docker Desktop
brew install --cask docker

Linux:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io docker-compose

# Enable and start Docker
sudo systemctl enable docker
sudo systemctl start docker

Windows: - Download and install Docker Desktop - Enable WSL 2 backend if prompted

2. Get GitHub Personal Access Token

The image needs access to private Artalytics repositories.

Create a PAT:

  1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
  2. Click “Generate new token (classic)”
  3. Set scopes:
    • ✅ repo (Full control of private repositories)
    • ✅ read:packages (Download packages from GitHub Package Registry)
  4. Generate and copy the token

Set the token:

# Linux/macOS
export GITHUB_PAT=ghp_your_token_here

# Windows PowerShell
$env:GITHUB_PAT="ghp_your_token_here"

# Windows CMD
set GITHUB_PAT=ghp_your_token_here

Persist it (optional):

# Add to ~/.bashrc or ~/.zshrc (Linux/macOS)
echo 'export GITHUB_PAT=ghp_your_token_here' >> ~/.bashrc

# Or use a .env file
echo "GITHUB_PAT=ghp_your_token_here" > .env
source .env

3. Clone artaverse Repository 

git clone https://github.com/artalytics/artaverse.git
cd artaverse

Building the Image

The simplest way to build:

# From artaverse repository root
./inst/docker-build.sh

This script: - ✅ Validates GITHUB_PAT is set - ✅ Builds image with tag artaverse:latest - ✅ Shows build progress - ✅ Displays success message with next steps

Expected output:

Building artaverse Docker image...
GITHUB_PAT: ✓ Set
Building image: artaverse:latest

[+] Building 1234.5s (12/12) FINISHED
...

✅ Build complete!
   Image: artaverse:latest
   Size: 2.45 GB

Next steps:
  docker run -it artaverse:latest

Option 2: Manual Build

For more control or custom tags:

# Build with specific tag
docker build \
  --build-arg GITHUB_PAT="$GITHUB_PAT" \
  -t artaverse:latest \
  -f inst/Dockerfile \
  .

# Build with version tag
docker build \
  --build-arg GITHUB_PAT="$GITHUB_PAT" \
  -t artaverse:0.0.1 \
  -f inst/Dockerfile \
  .

# Build without cache (force fresh install)
docker build \
  --no-cache \
  --build-arg GITHUB_PAT="$GITHUB_PAT" \
  -t artaverse:latest \
  -f inst/Dockerfile \
  .

Build Progress

The build process takes 15-20 minutes and includes:

  1. Base image pull (~500MB) - Rocker R 4.4.2
  2. System dependencies (~300MB) - ImageMagick, FFmpeg, etc.
  3. pak installation (~30 seconds) - Package manager
  4. artaverse installation (~8-10 minutes) - All 18 packages + deps
  5. Environment setup (~10 seconds) - .Rprofile configuration

Total: ~2.5GB final image

Using the Container

Interactive Bash Session

The default entry point is bash:

docker run -it artaverse:latest

You’ll see:

root@container:/workspace#

Now you can:

# Start R
R

# Run R commands
Rscript -e "library(artaverse); artaverse_versions()"

# Access artcore database functions
Rscript -e "library(artcore); cn <- dbc(); print(cn)"

# Use any bash tools
ls -la
git status

Interactive R Session

Start R directly with artaverse loaded:

docker run -it artaverse:latest -c "R"

The .Rprofile auto-loads artaverse:

✔ Artalytics Platform Ready
  • artaverse_packages()  - List all packages
  • artaverse_versions()  - Check versions
  • ?install_foundation   - See installation profiles

── Attaching Artalytics Platform artaverse 0.0.1 ──
✔ artcore     1.3.0    ✔ modArtist   0.0.7
✔ artutils    0.19.0    ✔ modBrowse   0.9.2
...

>

Run R Script from Host

Execute an R script from your local machine:

# Mount current directory and run script
docker run --rm \
  -v $(pwd):/workspace \
  artaverse:latest \
  -c "Rscript /workspace/my_analysis.R"

Mount Local Directory

Work with files from your host machine:

docker run -it \
  -v $(pwd):/workspace \
  -w /workspace \
  artaverse:latest

Now you can: - Edit files on your host with your IDE - Run R commands in the container - Files persist on your host after container stops

Run Platform App

Start the Shiny appPlatform:

docker run -it \
  -p 3838:3838 \
  -e ART_PGHOST=your_db_host \
  -e ART_PGUSER=your_db_user \
  -e ART_PGPASS=your_db_pass \
  artaverse:latest \
  -c "R -e 'library(appPlatform); run_app(host=\"0.0.0.0\", port=3838)'"

Access at: http://localhost:3838

GitHub Container Registry

Pulling Pre-built Images

If the image is published to GitHub Container Registry (GHCR):

# Pull latest
docker pull ghcr.io/artalytics/artaverse:latest

# Pull specific version
docker pull ghcr.io/artalytics/artaverse:0.0.1

# Run the pulled image
docker run -it ghcr.io/artalytics/artaverse:latest

Authenticating with GHCR

For private images:

# Login to GitHub Container Registry
echo $GITHUB_PAT | docker login ghcr.io -u USERNAME --password-stdin

# Then pull
docker pull ghcr.io/artalytics/artaverse:latest

Package Verification

Check Installed Packages

Verify all artaverse packages are installed:

docker run --rm artaverse:latest -c "R -e 'library(artaverse); artaverse_versions()'"

Expected output:

   package    version installed
1: artcore      1.3.0      TRUE
2: artutils    0.19.0      TRUE
3: artauth      0.1.2      TRUE
...
18: artsend     0.2.2      TRUE

Generate Full Inventory

Create a detailed package inventory:

# Using the inventory script
docker run --rm \
  -v $(pwd):/output \
  artaverse:latest \
  -c "/workspace/inst/docker-inventory.sh /output"

This creates artaverse-packages.csv with: - Package name - Version - Priority (direct/indirect dependency) - Installation status

Test Package Functionality

Run a quick smoke test:

docker run --rm artaverse:latest -c "R -e '
library(artaverse)

# Test core functions
stopifnot(exists(\"dbc\", where = asNamespace(\"artcore\")))
stopifnot(exists(\"get_artist_by_slug\", where = asNamespace(\"artutils\")))

# Test modules
stopifnot(requireNamespace(\"modBrowse\"))
stopifnot(requireNamespace(\"modGallery\"))

cat(\"✔ All tests passed\\n\")
'"

Advanced Usage

Development Workflow

Use the container for package development:

# Mount your package directory
docker run -it \
  -v ~/code/mypackage:/workspace \
  artaverse:latest

# Inside container
cd /workspace
R -e "devtools::check()"
R -e "devtools::test()"

CI/CD Integration

Use in GitHub Actions:

name: Test with artaverse

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/artalytics/artaverse:latest
      credentials:
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        run: |
          R -e "devtools::check()"

Custom Installation Profiles

Build images with specific profiles for smaller sizes:

Backend-only image:

FROM rocker/r-ver:4.4.2
# ... system deps ...
RUN R -e "install.packages('pak')"
ARG GITHUB_PAT
ENV GITHUB_PAT=$GITHUB_PAT
RUN R -e "pak::pkg_install('artalytics/artaverse'); library(artaverse); install_backend()"
ENTRYPOINT ["/bin/bash"]

Frontend-only image:

FROM rocker/r-ver:4.4.2
# ... basic system deps (no ImageMagick, FFmpeg) ...
RUN R -e "install.packages('pak')"
ARG GITHUB_PAT
ENV GITHUB_PAT=$GITHUB_PAT
RUN R -e "pak::pkg_install('artalytics/artaverse'); library(artaverse); install_frontend()"
ENTRYPOINT ["/bin/bash"]

Environment Variables

At Build Time

Pass secrets during build:

docker build \
  --build-arg GITHUB_PAT="$GITHUB_PAT" \
  -t artaverse:latest \
  -f inst/Dockerfile \
  .

At Runtime

Pass environment variables to container:

# Single variable
docker run -it \
  -e ART_PGHOST=localhost \
  artaverse:latest

# From .env file
docker run -it \
  --env-file .env \
  artaverse:latest

# Multiple variables
docker run -it \
  -e ART_PGHOST=localhost \
  -e ART_PGUSER=postgres \
  -e ART_PGPASS=secret \
  -e ART_OPENAI_KEY=sk-... \
  artaverse:latest

Required for Artalytics Apps 

# Database connection
ART_PGHOST=your-db-host
ART_PGPORT=5432
ART_PGUSER=your-db-user
ART_PGPASS=your-db-password

# CDN (DigitalOcean Spaces)
ART_BUCKETS_KEY_ID=your-key-id
ART_BUCKETS_KEY_SECRET=your-secret-key

# API Keys (optional)
ART_OPENAI_KEY=sk-...
ART_GEMINI_KEY=...
ART_OPENSEA_KEY=...
ART_RESEND_KEY=...

Docker Compose

For production deployments with multiple services:

docker-compose.yml:

version: '3.8'

services:
  artaverse:
    image: ghcr.io/artalytics/artaverse:latest
    container_name: artaverse-platform
    environment:
      - ART_PGHOST=postgres
      - ART_PGPORT=5432
      - ART_PGUSER=artalytics
      - ART_PGPASS=${DB_PASSWORD}
      - ART_BUCKETS_KEY_ID=${SPACES_KEY_ID}
      - ART_BUCKETS_KEY_SECRET=${SPACES_KEY_SECRET}
    ports:
      - "3838:3838"
    volumes:
      - ./data:/workspace/data
    depends_on:
      - postgres
    command: R -e "library(appPlatform); run_app(host='0.0.0.0', port=3838)"

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=artalytics
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=artalytics
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  pgdata:

Usage:

# Create .env file
cat > .env <<EOF
DB_PASSWORD=your_secure_password
SPACES_KEY_ID=your_key_id
SPACES_KEY_SECRET=your_secret_key
EOF

# Start services
docker-compose up -d

# View logs
docker-compose logs -f artaverse

# Stop services
docker-compose down

Troubleshooting

Build Issues

Problem: GITHUB_PAT must be set

Solution:

# Verify PAT is set
echo $GITHUB_PAT

# If empty, set it
export GITHUB_PAT=ghp_your_token_here

# Then rebuild
./inst/docker-build.sh

Problem: Authentication failed for artalytics/artcore

Solution:

# Verify PAT has repo scope
# Generate new PAT if needed with "repo" permission

# Test PAT works
curl -H "Authorization: token $GITHUB_PAT" \
  https://api.github.com/repos/artalytics/artcore

# Should return repo info, not 404

Problem: Out of disk space

Solution:

# Clean Docker system
docker system prune -a

# Check available space
docker system df

# Remove old images
docker images | grep artaverse | awk '{print $3}' | xargs docker rmi

Problem: Failed to install artpipelines - missing ImageMagick

Solution: The Dockerfile includes all system dependencies. If this fails:

# Rebuild without cache to ensure fresh system package install
docker build --no-cache \
  --build-arg GITHUB_PAT="$GITHUB_PAT" \
  -t artaverse:latest \
  -f inst/Dockerfile \
  .

Runtime Issues

Problem: Container exits immediately

Solution:

# Bash entry point requires -it flags for interactive session
docker run -it artaverse:latest

# Or run specific command
docker run --rm artaverse:latest -c "R --version"

Problem: Cannot access database from container

Solution:

# Check network connectivity
docker run --rm artaverse:latest -c "ping -c 3 your-db-host"

# Use host network mode (Linux only)
docker run -it --network host artaverse:latest

# On macOS/Windows, use host.docker.internal
docker run -it \
  -e ART_PGHOST=host.docker.internal \
  artaverse:latest

Problem: Port already in use (3838)

Solution:

# Map to different host port
docker run -it \
  -p 8080:3838 \
  artaverse:latest \
  -c "R -e 'library(appPlatform); run_app(port=3838)'"

# Access at http://localhost:8080

Problem: R packages not found

Solution:

# Verify packages installed
docker run --rm artaverse:latest -c "R -e 'artaverse::artaverse_versions()'"

# If packages missing, rebuild image
./inst/docker-build.sh

Image Management

List Images 

docker images | grep artaverse

Tag Images 

# Tag with version
docker tag artaverse:latest artaverse:0.0.1

# Tag for GHCR
docker tag artaverse:latest ghcr.io/artalytics/artaverse:latest
docker tag artaverse:latest ghcr.io/artalytics/artaverse:0.0.1

Push to GitHub Container Registry 

# Login to GHCR
echo $GITHUB_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

# Push images
docker push ghcr.io/artalytics/artaverse:latest
docker push ghcr.io/artalytics/artaverse:0.0.1

Note: Automated builds via GitHub Actions are recommended (see GitHub Workflow section below).

Remove Images 

# Remove specific tag
docker rmi artaverse:latest

# Remove all artaverse images
docker images | grep artaverse | awk '{print $3}' | xargs docker rmi

GitHub Workflow for Automated Builds

The repository includes a GitHub Actions workflow that automatically builds and publishes the Docker image to GitHub Container Registry.

Workflow file: .github/workflows/docker-publish.yml

Triggers: - Push to main branch (for stable releases) - Manual workflow dispatch (for testing) - Schedule: Weekly on Sundays at 2 AM UTC (to pick up dependency updates)

What it does: 1. Checks out repository 2. Sets up Docker Buildx 3. Logs in to GitHub Container Registry 4. Builds image with GITHUB_TOKEN 5. Tags with latest and version number 6. Pushes to ghcr.io/artalytics/artaverse

To use the automated image:

# Pull latest automated build
docker pull ghcr.io/artalytics/artaverse:latest

# Run it
docker run -it ghcr.io/artalytics/artaverse:latest

Example Workflows

Data Analysis Script 

# Create analysis script on host
cat > analyze.R <<'EOF'
library(artaverse)
library(artcore)

# Connect to database
cn <- dbc()

# Run analysis
results <- artutils::get_artist_stats("artist-slug")
print(results)

# Cleanup
dbd(cn)
EOF

# Run in container with DB credentials
docker run --rm \
  -v $(pwd):/workspace \
  -e ART_PGHOST=your-db-host \
  -e ART_PGUSER=your-db-user \
  -e ART_PGPASS=your-db-password \
  artaverse:latest \
  -c "Rscript /workspace/analyze.R"

Generate Certificate 

docker run --rm \
  -v $(pwd)/output:/workspace/output \
  -e ART_PGHOST=your-db-host \
  -e ART_PGUSER=your-db-user \
  -e ART_PGPASS=your-db-password \
  artaverse:latest \
  -c "R -e 'library(artpixeltrace); cert <- generate_certificate(artwork_id); save(cert, file=\"/workspace/output/cert.pdf\")'"

Run Batch Pipeline 

docker run --rm \
  -v $(pwd)/data:/workspace/data \
  -e ART_PGHOST=your-db-host \
  -e ART_OPENAI_KEY=sk-... \
  artaverse:latest \
  -c "R -e 'library(artpipelines); process_batch(\"/workspace/data\")'"

Package Development 

# Mount package directory
docker run -it \
  -v ~/code/mynewpkg:/workspace \
  artaverse:latest

# Inside container
R -e "devtools::load_all()"
R -e "devtools::test()"
R -e "devtools::check()"
R -e "devtools::document()"

Performance Optimization

Layer Caching

Docker caches layers during build. To optimize:

# ✅ GOOD: Stable layers first
FROM rocker/r-ver:4.4.2
RUN apt-get update && apt-get install ...  # Cached
RUN R -e "install.packages('pak')"         # Cached

# Frequently changing layer last
RUN R -e "pak::pkg_install('artalytics/artaverse')"  # Re-runs when code changes

Multi-stage Builds

For smaller production images:

# Build stage
FROM rocker/r-ver:4.4.2 AS builder
RUN apt-get update && apt-get install ...
ARG GITHUB_PAT
ENV GITHUB_PAT=$GITHUB_PAT
RUN R -e "pak::pkg_install('artalytics/artaverse'); library(artaverse); install_platform(include_extended=TRUE)"

# Runtime stage
FROM rocker/r-ver:4.4.2
RUN apt-get update && apt-get install --no-install-recommends \
    libmagick++-6.q16-8 \  # Runtime libs only, not dev
    libavfilter7
COPY --from=builder /usr/local/lib/R/site-library /usr/local/lib/R/site-library
ENTRYPOINT ["/bin/bash"]

BuildKit

Enable BuildKit for faster, more efficient builds:

# One-time
export DOCKER_BUILDKIT=1

# Then build normally
docker build ...

Summary

The artaverse Docker image provides a complete, reproducible R environment with:

  • ✅ All 18 Artalytics packages installed
  • ✅ Full dependency tree (~180 packages)
  • ✅ System libraries for heavy processing
  • ✅ Ready for interactive use or automation
  • ✅ Bash entry point for maximum flexibility
  • ✅ Auto-loading artaverse in R sessions

Quick start:

export GITHUB_PAT=your_token
git clone https://github.com/artalytics/artaverse.git
cd artaverse
./inst/docker-build.sh
docker run -it artaverse:latest

For automated builds, the GitHub workflow publishes to ghcr.io/artalytics/artaverse:latest.