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.
Building from source gives you full control over the build process and is ideal for development, testing, or creating custom builds.
Prerequisites RiftRelay requires Go 1.26.0 or later . Check your version with go version.
Quick Start
Clone the repository
git clone https://github.com/renja-g/RiftRelay.git cd RiftRelay
Set environment variables
export RIOT_TOKEN = "your-riot-token"
Run the application
The server starts on http://localhost:8985 by default.
Test it's working
curl http://localhost:8985/healthz
Development Workflow Running with go run For development, use go run to compile and run in one step:
Basic
With Environment Variables
Inline Variables
Hot Reloading For automatic recompilation on file changes, use air :
# Install air go install github.com/cosmtrek/air@latest # Run with hot reload air
Production Build Basic Build Create an optimized production binary:
Run the binary:
export RIOT_TOKEN = "your-token" ./riftrelay
Optimized Build Create a smaller, stripped binary:
CGO_ENABLED = 0 go build -trimpath -ldflags= "-s -w" -o riftrelay .
Build flags explained:
CGO_ENABLED=0-trimpath-ldflags="-s -w"
The optimized build produces a binary ~40% smaller than the basic build and is more portable.
Build for different platforms:
Linux (amd64)
Linux (arm64)
macOS (Apple Silicon)
Windows
GOOS = linux GOARCH = amd64 CGO_ENABLED = 0 go build -trimpath -ldflags= "-s -w" -o riftrelay-linux-amd64 .
Testing Run All Tests Run Tests with Coverage Run Tests with Race Detection Detect race conditions in concurrent code:
go test -race ./internal/config ./internal/router ./internal/limiter ./internal/proxy
Race detection significantly slows down tests but is essential for catching concurrency bugs.
Run Specific Package Tests # Test only the limiter package go test ./internal/limiter # With verbose output go test -v ./internal/limiter
Benchmarks Run performance benchmarks:
go test -run '^$' -bench . -benchmem ./internal/limiter ./internal/proxy
Flags explained:
-run '^$'-bench .-benchmem
Benchmarks help identify performance regressions and optimize critical code paths.
Sample Benchmark Output goos: linux goarch: amd64 pkg: github.com/renja-g/RiftRelay/internal/limiter BenchmarkAdmit-8 1000000 1023 ns/op 128 B/op 2 allocs/op BenchmarkSchedule-8 500000 2456 ns/op 256 B/op 4 allocs/op
Environment Setup Using .env File Create a .env file in the project root:
# Copy example cp .env.example .env # Edit with your values nano .env
Example .env:
RIOT_TOKEN = your-riot-token PORT = 8985 ENABLE_METRICS = true ENABLE_PPROF = false ENABLE_SWAGGER = true QUEUE_CAPACITY = 2048 ADMISSION_TIMEOUT = 5m SHUTDOWN_TIMEOUT = 20s
Load environment variables:
# Using export (bash/zsh) export $( cat .env | xargs ) # Or use a tool like direnv direnv allow .
Multiple Riot Tokens Supply multiple tokens for better throughput:
export RIOT_TOKEN = "token1,token2,token3" go run .
RiftRelay automatically load-balances requests across all provided tokens.
Project Structure Understanding the codebase:
RiftRelay/ ├── main.go # Entry point and signal handling ├── internal/ │ ├── app/ # Server lifecycle and routing │ ├── config/ # Environment configuration │ ├── router/ # Path parsing and bucket keys │ ├── limiter/ # Admission control and scheduling │ ├── proxy/ # Reverse proxy adapter │ ├── transport/ # HTTP transport configuration │ └── metrics/ # Metrics collection ├── go.mod # Go module definition ├── go.sum # Dependency checksums ├── Dockerfile # Container build instructions └── docker-compose.yml # Compose configuration
Development Commands # Format code go fmt ./... # Check formatting gofmt -l .
Linting # Install golangci-lint go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest # Run linter golangci-lint run
Dependency Management # Download dependencies go mod download # Verify dependencies go mod verify # Tidy dependencies (remove unused) go mod tidy # Vendor dependencies (optional) go mod vendor
Debugging Enable Debug Endpoints Enable pprof for profiling:
ENABLE_PPROF = true go run .
Access profiling endpoints:
CPU profile: http://localhost:8985/debug/pprof/profile
Heap profile: http://localhost:8985/debug/pprof/heap
Goroutines: http://localhost:8985/debug/pprof/goroutine
Using Delve Debugger Install and use Delve :
# Install delve go install github.com/go-delve/delve/cmd/dlv@latest # Debug with delve dlv debug .
Troubleshooting Go Version Issues Check Go version:
If you have an older version, upgrade:
# Download from https://go.dev/dl/ # Or use a version manager like gvm gvm install go1.26.0 gvm use go1.26.0
Module Errors If you see module-related errors:
# Clear module cache go clean -modcache # Re-download dependencies go mod download
Port Already in Use Change the port:
Or find what’s using port 8985:
# Linux/macOS lsof -i :8985 # Kill the process kill -9 < PI D >
Missing RIOT_TOKEN If you see an error about missing RIOT_TOKEN:
export RIOT_TOKEN = "your-token" go run .
The RIOT_TOKEN environment variable is required. RiftRelay will not start without it.
Production Deployment Systemd Service Create a systemd service for Linux:
# /etc/systemd/system/riftrelay.service [Unit] Description =RiftRelay API Proxy After =network.target [Service] Type =simple User =riftrelay WorkingDirectory =/opt/riftrelay EnvironmentFile =/opt/riftrelay/.env ExecStart =/opt/riftrelay/riftrelay Restart =on-failure RestartSec =5s [Install] WantedBy =multi-user.target
Enable and start:
sudo systemctl enable riftrelay sudo systemctl start riftrelay sudo systemctl status riftrelay
Process Manager (PM2) For non-systemd environments:
# Install PM2 npm install -g pm2 # Start with PM2 RIOT_TOKEN = "your-token" pm2 start ./riftrelay --name riftrelay # Save PM2 config pm2 save pm2 startup
For production deployments, Docker is recommended for easier management and better isolation. See Docker Deployment . Next Steps
Configuration Configure RiftRelay for your needs
Docker Deployment Deploy with Docker for production