Set Up Docker Compose

Configure Docker Compose for R development and deployment environments.

When to Use

• Running R alongside other services (databases, APIs)
• Setting up a reproducible development environment
• Orchestrating an R-based MCP server container
• Managing environment variables and volume mounts

Inputs

• Required: Dockerfile for the R service
• Required: Project directory to mount
• Optional: Additional services (database, cache, web server)
• Optional: Environment variable configuration

Procedure

Step 1: Create docker-compose.yml

version: '3.8'

services:
  r-dev:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: r-dev
    image: r-dev:latest

    volumes:
      - .:/workspace
      - renv-cache:/workspace/renv/cache

    stdin_open: true
    tty: true

    environment:
      - TERM=xterm-256color
      - R_LIBS_USER=/workspace/renv/library
      - RENV_PATHS_CACHE=/workspace/renv/cache

    command: R

    restart: unless-stopped

volumes:
  renv-cache:
    driver: local

Expected: A

docker-compose.yml

file exists with the R service defined, including volume mounts for the project directory and renv cache, and environment variables for R library paths.

On failure: If YAML syntax is invalid, validate with

docker compose config

. Ensure indentation uses spaces (not tabs) and all string values with special characters are quoted.

Step 2: Add Additional Services (If Needed)

services:
  r-dev:
    # ... as above
    depends_on:
      - postgres
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432

  postgres:
    image: postgres:16
    container_name: r-postgres
    environment:
      POSTGRES_DB: analysis
      POSTGRES_USER: ruser
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  renv-cache:
  pgdata:

Expected: The additional service (e.g., PostgreSQL) is defined with its own volume, environment variables, and port mapping. The R service has

depends_on

referencing the new service.

On failure: If the database service fails to start, check

docker compose logs postgres

for initialization errors. Verify that environment variables like

POSTGRES_PASSWORD_FILE

point to valid secrets or switch to

POSTGRES_PASSWORD

for development.

Step 3: Configure Networking

For services that need localhost access (e.g., MCP servers):

services:
  r-dev:
    network_mode: "host"

For isolated networking:

services:
  r-dev:
    networks:
      - app-network
    ports:
      - "3000:3000"

networks:
  app-network:
    driver: bridge

Expected: Networking is configured appropriately:

host

mode for services needing localhost access (MCP servers), or bridge networking with explicit port mappings for isolated services.

On failure: If services cannot communicate, verify they are on the same network. With bridge networking, use service names as hostnames (e.g.,

postgres

not

localhost

). With host mode, use

localhost

and ensure ports do not conflict.

Step 4: Manage Environment Variables

Create

.env

file (git-ignored):

R_VERSION=4.5.0
GITHUB_PAT=your_token_here

Reference in compose:

services:
  r-dev:
    build:
      args:
        R_VERSION: ${R_VERSION}
    env_file:
      - .env

Expected: A

.env

file exists (git-ignored) with project-specific variables, and

docker-compose.yml

references it via

env_file

or variable interpolation (

${VAR}

).

On failure: If variables are not resolving, ensure the

.env

file is in the same directory as

docker-compose.yml

. Run

docker compose config

to see the resolved configuration with all variables expanded.

Step 5: Build and Run

# Build images
docker compose build

# Start services
docker compose up -d

# Attach to R session
docker compose exec r-dev R

# View logs
docker compose logs -f r-dev

# Stop services
docker compose down

Expected: All services start. R session accessible.

On failure: Check

docker compose logs

for startup errors. Common: port conflicts, missing environment variables.

Step 6: Create Override for Development

Create

docker-compose.override.yml

for local development settings:

services:
  r-dev:
    volumes:
      - /path/to/local/packages:/extra-packages
    environment:
      - DEBUG=true

This is automatically merged with

docker-compose.yml

.

Expected: A

docker-compose.override.yml

file exists with development-specific settings (extra volumes, debug flags) that are automatically applied when running

docker compose up

.

On failure: If overrides are not taking effect, verify the filename is exactly

docker-compose.override.yml

. Run

docker compose config

to confirm the merge. For explicit override files, use

docker compose -f docker-compose.yml -f custom-override.yml up

.

Validation

• docker compose build

  completes without errors

• docker compose up

  starts all services
• Volume mounts correctly share files between host and container
• Environment variables are available inside containers
• Services can communicate with each other

• docker compose down

  cleanly stops everything

Common Pitfalls

• Volume mount permissions: Linux containers may create files as root. Use

  user:

  directive or fix permissions.
• Port conflicts: Check for services already using the same ports on the host
• Docker Desktop vs CLI:

  docker compose

  (v2) vs

  docker-compose

  (v1). Use v2.
• WSL path mounts: Use

  /mnt/c/...

  paths when mounting Windows directories from WSL
• Named volumes vs bind mounts: Named volumes persist across rebuilds; bind mounts reflect host changes immediately

Related Skills

• create-r-dockerfile

  - create the Dockerfile that compose references

• containerize-mcp-server

  - compose configuration for MCP servers

• optimize-docker-build-cache

  - speed up compose builds