$docker.recipes

Skipper HTTP Router

intermediate

HTTP router and reverse proxy for service composition.

[i]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

  • [1]Microservice API gateway requiring complex routing logic beyond path-based rules
  • [2]A/B testing infrastructure with weighted traffic distribution between service versions
  • [3]Multi-tenant SaaS platforms needing per-tenant routing and authentication
  • [4]Legacy application modernization with gradual traffic migration patterns
  • [5]Development environment proxy for testing Kubernetes ingress configurations locally
  • [6]High-traffic e-commerce platforms requiring circuit breaker protection
  • [7]API 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
[!]

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

[$]docker-compose.yml

[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

[i]Usage Notes

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

## Tags

#skipper#router#proxy#kubernetes#zalando

## Category

Web Servers & Reverse Proxies

## Related