Creating coherent Networks for docker development

Docker is a great tool for developing micro services that may be composed together in order to form a larger application. However, Docker containers run in a network apart from the host machine. That makes it sometimes cumbersome and complicated to use common host names within the Docker network and the host network. In this article we’ll show a simple knack that may be applied in order to use identical host names in both networks.

Imagine a situation where two servers run in a shared Docker network as described by the following code snippet from a docker-compose.yml:

...
networks:
  network-web:

services:
  web-server:
    image: nginx:stable-alpine
    container_name: web-server
    networks:
      - network-web
    ports:
      - "8080:8080"
   ...

  keycloak-server:
    image: quay.io/keycloak/keycloak:15.0.2
    container_name: keycloak-server
    networks:
      - network-web
    ports:
      - "8081:8080"
   ...

The web server uses KeyCloak as an IDP, i.e. for authentication. Typically you will let your browser point to “http://localhost:8080/” during development to test your application. But how do you redirect to the KeyCloak server for login? Internally the web server can “talk” to the other server by using the given container name. But the browser cannot use to that host name, because it is only valid within the Docker network.

A common solution is to use a reverse proxy that will redirect all requests. But that may cause configuration problems, e.g. when KeyCloak has to be configured for valid redirects URIs after successful login.

Create entrIES in /etc/hosts

In the first step of our solution we create an additional entry in the /etc/hosts file (%windir%\system32\drivers\etc in Windows). You will need administrative rights to do that.

# KeyCloak IDP and application server

127.0.0.1       idp.auth.com www.myapplication.com

This will create an alias of the host machine, i.e. using the command

traceroute www.myapplication.com 

will be resolved to the loopback device of your computer. In order to avoid confusion you should not use existing domains for this purpose or take special care.

Add extra hosts in docker compose file

Second, create some additional line in the docker-compose.yml:

...
networks:
  network-web:

services:
  web-server:
    image: nginx:stable-alpine
    container_name: web-server
    networks:
      - network-web
    ports:
      - "8080:8080"
    extra_hosts:
      - "idp.auth.com:host-gateway"
      - "www.myapplication.com:host-gateway"
   ...

  keycloak-server:
    image: quay.io/keycloak/keycloak:15.0.2
    container_name: keycloak-server
    networks:
      - network-web
    ports:
      - "8081:8080"
    extra_hosts:
      - "idp.auth.com:host-gateway"
      - "www.myapplication.com:host-gateway"

This will add idp.auth.com and www.myapplication.com as a host names to the Docker network, where the magic variable host-gateway resolves to the docker host.

The solution

In effect, in both networks the name idp.auth.com can now be resolved and point to the same instance. Thus in our example application the web server may uniformly use the URI http://idp.auth.com:8081/auth in order to address the KeyCloak server and both the Docker container and the browser will be able to resolve the name. Accordingly, KeyCloak can be configured to use http://www.myapplication.com:8081 as a valid URI for redirection.

markus.dahm@akquinet.de