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

Hosting Under a Subpath

When serving the API reference under a subpath (for example, behind a reverse proxy at /docs), set the BASE_PATH environment variable so the container generates URLs with the correct prefix:

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

BASE_PATH only changes the URLs the client requests (such as /docs/configuration.json and mounted document URLs). It does not change the internal Caddy routes, so your reverse proxy or ingress is still expected to strip the prefix before forwarding requests to the container.

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.