Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/renja-g/RiftRelay/llms.txt

Use this file to discover all available pages before exploring further.

Docker Compose provides a declarative way to deploy RiftRelay with all configuration in version-controlled files.

​
Quick Setup

The fastest way to get started is using the automated setup script: 
curl -fsSL "https://raw.githubusercontent.com/renja-g/RiftRelay/main/scripts/setup-docker-stack.sh" | bash
The script downloads docker-compose.yml and .env.example, prompts for your Riot API token, and starts RiftRelay automatically.

​
Manual Setup

1

Create project directory

mkdir riftrelay && cd riftrelay
2

Create docker-compose.yml

Download the compose file or create it manually:
curl -O https://raw.githubusercontent.com/renja-g/RiftRelay/main/docker-compose.yml
3

Create .env file

Create a .env file with your configuration:
curl -O https://raw.githubusercontent.com/renja-g/RiftRelay/main/.env.example
mv .env.example .env
Edit .env and add your Riot token:
nano .env
4

Start the service

docker compose up -d
5

Verify it's running

curl http://localhost:8985/healthz

​
Configuration Files

​
docker-compose.yml

The official docker-compose.yml includes production-ready settings: 
name: riftrelay

services:
  riftrelay:
    build:
      context: .
      dockerfile: Dockerfile
    image: ${RIFTRELAY_IMAGE:-renjag/riftrelay:latest}
    restart: unless-stopped
    init: true
    env_file:
      - .env
    environment:
      PORT: "8985"
    ports:
      - "8985:8985"
    healthcheck:
      test: ["CMD-SHELL", "wget --spider -q http://127.0.0.1:8985/healthz || exit 1"]
      interval: 15s
      timeout: 3s
      retries: 3
      start_period: 20s
    read_only: true
    tmpfs:
      - /tmp:size=64m,mode=1777
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    stop_grace_period: 25s
The compose file uses ${RIFTRELAY_IMAGE:-renjag/riftrelay:latest} which allows you to override the image in your .env file or use the default Docker Hub image.

​
.env File

Create a .env file in the same directory as docker-compose.yml: 
# Required: Riot token (comma separated for multiple tokens)
RIOT_TOKEN=your-riot-token

# Optional: RiftRelay image to pull/run in docker compose
RIFTRELAY_IMAGE=renjag/riftrelay:latest

# Optional overrides (RiftRelay)
PORT=8985
ENABLE_METRICS=true
ENABLE_PPROF=false
ENABLE_SWAGGER=true
SHUTDOWN_TIMEOUT=20s
Never commit your .env file to version control. Add it to .gitignore to prevent accidentally exposing your Riot API token.

​
Service Configuration

​
Restart Policy

restart: unless-stopped
The service automatically restarts unless explicitly stopped. This ensures high availability.

​
Init System

init: true
Uses tini as PID 1 to properly handle signals and reap zombie processes.

​
Health Checks

healthcheck:
  test: ["CMD-SHELL", "wget --spider -q http://127.0.0.1:8985/healthz || exit 1"]
  interval: 15s
  timeout: 3s
  retries: 3
  start_period: 20s
  • interval: Check every 15 seconds
  • timeout: Fail if check takes longer than 3 seconds
  • retries: Mark unhealthy after 3 consecutive failures
  • start_period: Grace period of 20 seconds after container starts
Check health status: 
docker compose ps

​
Security Settings

read_only: true
tmpfs:
  - /tmp:size=64m,mode=1777
These settings provide defense-in-depth:
  • read_only: Container filesystem is immutable
  • tmpfs: Writable /tmp in memory (64MB limit)
  • cap_drop: Drops all Linux capabilities
  • no-new-privileges: Prevents gaining additional privileges
These security settings follow container security best practices and should be kept enabled in production.

​
Graceful Shutdown

stop_grace_period: 25s
Gives the application 25 seconds to drain in-flight requests before forcefully stopping. This is 5 seconds more than the default SHUTDOWN_TIMEOUT (20s) to ensure clean shutdown.

​
Environment Variables

All RiftRelay configuration can be set in the .env file:
VariableDefaultDescription
RIOT_TOKENrequiredRiot API token (comma-separated for multiple)
RIFTRELAY_IMAGErenjag/riftrelay:latestDocker image to use
PORT8985Server port
QUEUE_CAPACITY2048Maximum queued requests
ADMISSION_TIMEOUT5mMax wait time in queue
SHUTDOWN_TIMEOUT20sGraceful shutdown timeout
ENABLE_METRICSfalseEnable /metrics endpoint
ENABLE_PPROFfalseEnable pprof endpoints
ENABLE_SWAGGERtrueEnable Swagger UI
See the Configuration page for all available options.

​
Managing the Service

​
Starting and Stopping

# Start in background
docker compose up -d

# Start with logs
docker compose up

​
Viewing Logs

docker compose logs -f

​
Updating

1

Pull latest image

docker compose pull
2

Restart with new image

docker compose up -d
3

Clean up old images

docker image prune
Docker Compose automatically recreates containers when the image changes.

​
Production Deployment

​
Resource Limits

Add resource limits to your docker-compose.yml: 
services:
  riftrelay:
    # ... other config ...
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

​
Multiple Instances

Scale the service for higher throughput: 
docker compose up -d --scale riftrelay=3
When scaling, you’ll need a load balancer. Multiple instances sharing the same RIOT_TOKEN will compete for rate limits.

​
Using Multiple Tokens

For better throughput with multiple tokens, set them in .env: 
RIOT_TOKEN=token1,token2,token3
RiftRelay automatically load-balances requests across all tokens.

​
Monitoring

Enable metrics and health checks: 
# Enable metrics in .env
ENABLE_METRICS=true

# Check health
curl http://localhost:8985/healthz

# View metrics
curl http://localhost:8985/metrics

​
Troubleshooting

​
Service won’t start

Check service status: 
docker compose ps
View detailed logs: 
docker compose logs riftrelay
Common issues:
  • Missing or invalid RIOT_TOKEN in .env
  • Port 8985 already in use
  • Syntax errors in docker-compose.yml

​
Configuration not applying

Recreate containers after changing .env: 
docker compose up -d --force-recreate

​
Permission errors

The container runs as non-root user app. If you mount volumes, ensure correct permissions: 
chown -R 1000:1000 /path/to/volume

​
Port conflicts

Change the host port in docker-compose.yml: 
ports:
  - "9000:8985"  # Use port 9000 on host

​
Next Steps

Configuration

Explore all configuration options

Usage

Learn how to use RiftRelay

Build docs developers (and LLMs) love

Get started for freeTalk to us