Entry page & reverse proxy for all your docker-compose projects. 🐳
Switch branches/tags
Nothing to show
Clone or download
Latest commit 441c3b1 Oct 24, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
common Improved Template Sep 25, 2017
contrib Improve Linux Support Oct 13, 2018
dns Basic Template Page Sep 25, 2017
docker Improve Linux Support Oct 13, 2018
http Improve Linux Support Oct 13, 2018
resources Improve Linux Support Oct 13, 2018
.gitignore Massiv improvements to the build script Sep 26, 2017
LICENSE ✏️ Fix LICENSE Sep 26, 2017
Makefile Ensure Version doe not contain newline Oct 13, 2018
README.md Improve Linux Support Oct 13, 2018
VERSION Improve Linux Support Oct 13, 2018
go.mod Improve Linux Support Oct 13, 2018
go.sum Improve Linux Support Oct 13, 2018
reception.go Improve Linux Support Oct 13, 2018



A dashboard and reverse proxy for your docker-compose projects. It does not require any dependencies but Docker and docker-compose.



This program shows all docker-compose projects that are running on a handy overview page. It has a built-in reverse-proxy, so that any container's exposed port are accessible as 'container.compose-project.docker'. In order to be able to resolve 'anything.docker' to localhost, this tool also ships a tiny tiny DNS server.

As a result, you'll be able to access your docker-compose projects as 'container.compose-project.docker', and the traffic will automatically be forwarded to the corresponding port, even as you fire up and shut down new docker-compose projects.


You need to have superuser privileges on your computer.


We assume you have Docker and docker-compose already installed.

But for resolving *.docker to localhost (i.e. or ::1), changes to your host configuration are required.


Install reception:

git clone https://github.com/ninech/reception.git

Proceed according to your linux configuration:

Ubuntu 16.04/18.04

Instead of .docker as TLD it's the easiest to just use .localhost because that's already built-in in the systemd-resolver.service.

Now run reception:

sudo reception -tld localhost

Or install reception as systemd service:

sudo make install

Now try to go to http://reception.localhost.

Local dnsmasq resolver

If you use dnsmasq as your local resolver, add this line to your dnsmasq config:


It tells dnsmasq to resolve *.docker with the dnsserver listening at (which will be reception). Then restart dnsmasq:

service dnsmasq restart

And now run reception:

sudo reception

You should be able to http://reception.docker now.

Non-systemd linux

Check the content of /etc/hosts. If it doesn't contain any nameservers pointing to, or ::1, then this way of installation should work for you:

sudo -i
mkdir /etc/resolver
echo "nameserver ::1" > /etc/resolver/docker
echo "nameserver" >> /etc/resolver/docker

Now run reception:

sudo reception

Finally, try to go to http://reception.docker.


Install reception using homebrew:

brew tap ninech/reception
brew install ninech/reception/reception

Next you need to register reception as the resolver for the docker TLD. Run the following on your command-line

sudo -s
mkdir /etc/resolver
echo "nameserver ::1" > /etc/resolver/docker
echo "nameserver" >> /etc/resolver/docker

At last, start the service:

sudo brew services start ninech/reception/reception

Now try to go to http://reception.docker.




reception is customizable to some extend. See reception -h for a complete list of configuration parameters.

$ reception -h
(c) 2017 Nine Internet Solutions AG
Usage of reception:
  -dns.address string
    	Defines on which address and port the HTTP daemon listens. (default "localhost:53")
  -docker.endpoint string
    	How reception talks to Docker. (default "unix:///var/run/docker.sock")
  -http.address string
    	Defines on which address and port the HTTP daemon listens. (default "localhost:80")
  -tld string
    	Defines on which TLD to react for HTTP and DNS requests. Should end with a "." . (default "docker.")
  -v	Show version.
    	Show version.

Tips & Tricks

"Main" container

The "main" container defines, where the project address ends up (i.e. http://yourproject.docker): The container should either have a docker-compose label of reception.main or should be called app:

version: '2'
  app:    <----- like this
    image: nginx
      reception.main: 'true'  <--- or like this
      - 80


In your docker-compose.yaml file, we advice to not specify a local port and to not export any unnecessary ports either. docker-compose will bind your exported port to any available local port, and reception will make sure, that there's a url for it.

This way, you can launch several containers that expose the same port without conflict and therefore avoid port collisions across projects.


version: '2'
    image: nginx
    depends_on: pgsql
        - 80    <----- like this
    image: postgresql


version: '2'
    image: nginx
    depends_on: pgsql
        - 80:80    <----- and _not_ like this (local port)
    image: postgresql
        - 5432:5432    <----- and _not_ like this (unnecessary port)


In order to detect which port of you container "the http port" is, reception looks for the well-known ports 80, 8080 and 3000. You can override this behaviour by setting the label reception.http-port to a port of your choice:

version: '2'
    image: special
        reception.http-port: '1234'  <--- like this
        - 1234


Reception can't bind to the ports

You must run reception as privileged user (i.e. root) for it to be able to bind to port 53 (dns) and port 80 (http).

docker-compose projects can't start because of port conflicts

Most probably you assigned a fixed port mapping for an exposed port. Look for something like the following:

version: 2
      - "8000:80"  <---- like this

In the case above, you would just replace "8000:80" with 80.

reception.docker does not resolve

First, check if reception is actually running.

Then see if nslookup reception.docker resolves to or ::1 (respectively nslookup reception.localhost on Ubuntu).

If it doesn't, please flush the DNS cache:

# macOS
sudo killall -HUP mDNSResponder

# Linux
systemctl restart named
# or
systemctl restart nscd


We depend on at least Go 1.11.

There is a Makefile with targets for any common task.

Don't just use go build, as it will not bundle the resources!


To build the project, run:



To run a snapshot of the project, run:

make run


To cut a release of the project, adjust the VERSION file and run:

make release

Debug the Makefile

To see the commands executed by make, run make as follows:

make <target> VERBOSE=1

To run make without having it execute any command, run make as follows:

make -n <target>


To cleanup afterwards, run:

make clean


This program is available as open source under the terms of the MIT License.


This piece of software is currently maintained and funded by nine.

logo of the company 'nine'