Skipper HTTP Router

intermediate

HTTP router and reverse proxy for service composition.

Overview

Skipper is Zalando's production-grade HTTP router and reverse proxy designed for high-performance service composition in cloud-native environments. Born from real-world needs at one of Europe's largest e-commerce platforms, Skipper handles billions of requests daily and offers unique capabilities through its Eskip domain-specific language for dynamic route configuration. Unlike traditional reverse proxies, Skipper focuses on request filtering, transformation, and intelligent routing with built-in support for circuit breakers, authentication, and rate limiting. This Docker Compose stack demonstrates Skipper's core functionality by providing both file-based route configuration through Eskip files and inline route definitions for immediate testing. The configuration showcases Skipper's flexibility by combining external route files with inline content serving, allowing developers to experiment with routing rules while maintaining production-ready configuration patterns. The setup exposes Skipper on port 9090 with volume mounting for persistent route definitions. This stack is ideal for platform engineers building microservice architectures, DevOps teams requiring advanced traffic management beyond basic load balancing, and organizations transitioning from traditional API gateways to more flexible routing solutions. Skipper's unique position as both a standalone proxy and Kubernetes ingress controller makes this configuration valuable for testing routing logic before deploying to orchestrated environments.

Key Features

Eskip DSL for declarative route configuration with predicates and filters
Built-in circuit breaker patterns with configurable failure thresholds
OAuth2 and JWT token validation filters for authentication workflows
Rate limiting with Redis backend support for distributed scenarios
Request and response transformation filters including header manipulation
Weighted routing for A/B testing and canary deployments
Metrics export in Prometheus format for observability integration
Hot-reload capability for route configuration changes without restarts

Common Use Cases

1Microservice API gateway requiring complex routing logic beyond path-based rules
2A/B testing infrastructure with weighted traffic distribution between service versions
3Multi-tenant SaaS platforms needing per-tenant routing and authentication
4Legacy application modernization with gradual traffic migration patterns
5Development environment proxy for testing Kubernetes ingress configurations locally
6High-traffic e-commerce platforms requiring circuit breaker protection
7API rate limiting and quota enforcement for third-party developer access

Prerequisites

Docker Engine 20.10+ and Docker Compose v2 for container orchestration
Minimum 512MB RAM allocated to Docker for Skipper's routing engine
Port 9090 available on host system for HTTP traffic routing
Basic understanding of HTTP routing concepts and reverse proxy principles
Familiarity with Eskip syntax for advanced route configuration
Backend services or test endpoints for meaningful routing scenarios

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  skipper: 
3    image: registry.opensource.zalan.do/teapot/skipper:latest
4    container_name: skipper
5    restart: unless-stopped
6    command: skipper -routes-file=/routes/routes.eskip -inline-routes='* -> inlineContent("Hello from Skipper") -> <shunt>'
7    volumes: 
8      - ./skipper/routes.eskip:/routes/routes.eskip:ro
9    ports: 
10      - "9090:9090"
11    networks: 
12      - skipper-network
13
14networks: 
15  skipper-network: 
16    driver: bridge

.env Template

.env

1# Skipper routes configuration

Usage Notes

1Docs: https://opensource.zalando.com/skipper/
2Zalando's battle-tested production router (handles billions of requests)
3Routes defined in .eskip files using Eskip DSL
4Example route: myRoute: Path("/api") -> "http://backend:8080"
5Built-in filters for auth, rate limiting, circuit breaker
6Kubernetes ingress controller mode available

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  skipper:
5    image: registry.opensource.zalan.do/teapot/skipper:latest
6    container_name: skipper
7    restart: unless-stopped
8    command: skipper -routes-file=/routes/routes.eskip -inline-routes='* -> inlineContent("Hello from Skipper") -> <shunt>'
9    volumes:
10      - ./skipper/routes.eskip:/routes/routes.eskip:ro
11    ports:
12      - "9090:9090"
13    networks:
14      - skipper-network
15
16networks:
17  skipper-network:
18    driver: bridge
19EOF
20
21# 2. Create the .env file
22cat > .env << 'EOF'
23# Skipper routes configuration
24EOF
25
26# 3. Start the services
27docker compose up -d
28
29# 4. View logs
30docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/skipper/run | bash

Troubleshooting

Error 'routes file not found': Ensure ./skipper/routes.eskip exists and contains valid Eskip syntax
Skipper returns 404 for all requests: Check that route predicates match incoming request patterns correctly
High memory usage during startup: Reduce route complexity or increase Docker memory limits above 512MB
Route changes not taking effect: Verify file permissions on mounted routes.eskip and restart container
Connection refused on port 9090: Check for port conflicts and ensure Docker port mapping is correct
Circuit breaker constantly open: Review backend service health and adjust failure threshold parameters

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

skipper

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download