Scalar API Reference Docker Image

Quick Start

Run the Docker container with your OpenAPI configuration:

docker run -p 8080:8080 -e API_REFERENCE_CONFIG='{"sources":[{"url": "https://registry.scalar.com/@scalar/apis/galaxy?format=json"}],"theme": "purple"}' scalarapi/api-reference:latest

Visit http://localhost:8080 to see your API reference.

Configuration

The Docker image supports two configuration methods:

1. Environment Variable

Set the API_REFERENCE_CONFIG environment variable with your Scalar configuration:

docker run -p 8080:8080 \
  -e API_REFERENCE_CONFIG='{"sources":[{"url":"https://api.example.com/openapi.json"}],"theme":"purple"}' \
  scalarapi/api-reference:latest

2. Document Mounting

Mount OpenAPI documents directly into the container for automatic discovery:

docker run -p 8080:8080 \
  -v /path/to/your/openapi-docs:/docs \
  scalarapi/api-reference:latest

The container automatically:

• Scans for OpenAPI documents (.json, .yaml, .yml files)
• Serves documents at /openapi/{filename}
• Generates titles from directory structure

Directory structure example:

/docs/
├── api-v1.json
├── internal/admin-api.yaml
└── external/partner-api.json

3. Combined Configuration

You can combine both approaches:

docker run -p 8080:8080 \
  -v /path/to/your/openapi-docs:/docs \
  -e API_REFERENCE_CONFIG='{"theme": "purple"}' \
  scalarapi/api-reference:latest

Docker Compose

services:
  api-reference:
    image: scalarapi/api-reference:latest
    ports:
      - "8080:8080"
    volumes:
      # Mount your OpenAPI documents directory
      - ./docs:/docs
    environment:
      # Optional: Add global configuration like theme
      # API_REFERENCE_CONFIG: |
      #   {
      #     "theme": "purple"
      #   }
    restart: unless-stopped

Environment Variables

Note: Either API_REFERENCE_CONFIG must be set OR documents must be mounted to /docs

Health Check

The container includes a health check endpoint at /health that returns OK with a 200 status code.

For detailed configuration options, refer to the main Scalar documentation.