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
::1), changes to your host configuration are required.
git clone https://github.com/nxt-engineering/reception.git make
Proceed according to your linux configuration:
.docker as TLD it's the easiest to just use
.localhost because that's already built-in in the
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
127.0.0.1:53 (which will be reception).
Then restart dnsmasq:
service dnsmasq restart
And now run reception:
You should be able to http://reception.docker now.
Check the content of
If it doesn't contain any nameservers pointing to
::1, then this way of installation should work for you:
sudo -i mkdir /etc/resolver echo "nameserver ::1" > /etc/resolver/docker echo "nameserver 127.0.0.1" >> /etc/resolver/docker
Now run reception:
Finally, try to go to http://reception.docker.
Install reception using homebrew:
brew tap nxt-engineering/reception brew install nxt-engineering/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 127.0.0.1" >> /etc/resolver/docker
At last, start the service:
sudo brew services start nxt-engineering/reception/reception
Now try to go to http://reception.docker.
reception is customizable to some extend.
reception -h for a complete list of configuration parameters.
$ ./reception --help (c) 2017-2018 Nine Internet Solutions AG (c) 2018-2019 nxt Engineering GmbH 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. -version Show version.
Tips & Tricks
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
version: '2' services: app: <----- like this image: nginx labels: reception.main: 'true' <--- or like this ports: - 80
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' services: app: image: nginx depends_on: pgsql ports: - 80 <----- like this pgsql: image: postgresql
version: '2' services: app: image: nginx depends_on: pgsql ports: - 80:80 <----- and _not_ like this (local port) pgsql: image: postgresql ports: - 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' services: app: image: special labels: reception.http-port: '1234' <--- like this ports: - 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 services: app: ports: - "8000:80" <---- like this
In the case above, you would just replace
reception.docker does not resolve
First, check if reception is actually running.
Then see if
nslookup reception.docker resolves to
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
This projects requires Go 1.11 or newer.
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:
To cut a release of the project, adjust the
VERSION file and run:
Debug the Makefile
To see the commands executed by
make as follows:
make <target> VERBOSE=1
make without having it execute any command, run
make as follows:
make -n <target>
To cleanup afterwards, run:
This program is available as open source under the terms of the MIT License.
This piece of software is currently maintained and funded by nxt.