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. 127.0.0.1 or ::1), changes to your host configuration are required.

Install reception:

git clone https://github.com/nxt-engineering/reception.git
make

Proceed according to your linux configuration:

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.

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

address=/docker/127.0.0.1

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:

sudo reception

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

Check the content of /etc/hosts. If it doesn't contain any nameservers pointing to 127.0.0.1, 127.0.0.53 or ::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:

sudo 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. See 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.

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'
services:
  app:    <----- like this
    image: nginx
    labels:
      reception.main: 'true'  <--- or like this
    ports:
      - 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.

Do

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

Don't

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

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).

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 "8000:80" with 80.

First, check if reception is actually running.

Then see if nslookup reception.docker resolves to 127.0.0.1 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

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:

make

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

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 nxt.