Skip to content
A «zero config» service name based router for docker swarm mode with a fresh more secure approach
Branch: master
Clone or download
Latest commit ca80aff Jan 29, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
files refactor port discovery Jan 23, 2019
src fix threading issue Jan 29, 2019
app.yml Cleanup sample stacks Jan 23, 2019 Add schema source Jun 22, 2018
testing.yml update image names Jan 23, 2019

Docker Build Status Docker Stars Docker Pulls Docker Automation Go Report


This is the «zero config» ingress router for Docker swarm mode deployments, based on the mature and superior haproxy library and a little of golang offering unique advantages:

  • Zero-copy using tcp splice syscall for real gbps throughput at very low cpu
  • No root privileges required
  • No docker socket mount required for service discovery
  • No external dependencies


Solves common docker swarm mode requirements:

  • Port overlapping due to service name publishing
  • Claim based service discovery
  • HTTP service forwarding
  • TLS service offloading eg. termination and forwarding
  • TLS service passthrough
  • Stackable as swarm or stack edge

Docker Swarm

Built for docker swarm mode docker swarm init ingress networking: Service discovery is based on claim resolution. Just define your service name urls as network alias names. Due to swarm lacking dns SRV support, port discovery is done by automatic port enumeration based on a default port list.

Mode 1 - Ingress routing

Simply get started having a swarm-router up and running. Now attach and define your app urls. The according inner port will be discoverd automaticly.

docker stack deploy -c swarm.yml swarm
docker stack deploy -c app.yml app

Now the endpoints below should be reachable:

Mode 2 - Ingress routing with isolated stacks

Deploying the same stack multiple times, eg. for development, testing and production, the service names collission can be avoided only by an additional router per stack. The according inner service name and port will be discoverd automaticly

Stack isolation

docker stack deploy -c swarm.yml swarm
docker stack deploy -c testing.yml testing
docker stack deploy -c production.yml production

Now the endpoints below should be reachable:



The inner communication of a stack can now be done with service shortnames eg. the service could reach simply a database using db as hostname. This makes portability of stages even simpler.

Override port discovery

Swarm-router does port discovery based on a default port list:

DEFAULT_BACKEND_PORTS=80 443 8000 8080 8443 9000

Alternatively port ovveride based on url startswith is possible:

OVERRIDE_BACKEND_PORTS=myapp:6457 myotherapp:7465


When TLS offloading comes into action, according fullchain certificates containing the private key should be provisioned on /certs host volume mount as Preferably this one should be mounted using docker secrets.


This one is built for high throughput and little CPU usage. Haproxy implements zero-copy and tcp-splicing based TCP handling. Even with golang now supporting splicing, haproxy is ways more superior in terms of cpu consumption and latency.


  • add termination with ACME autocerts
You can’t perform that action at this time.