Proxy

Short explaination

Usually you could reach your application via http://localhost:8080 from your browser. When using the proxy, you can use https and even define the URL under which your application is reachable, for example https://example.dev.localhost. Many websites have a redirect for www integrated, so https://www.example.dev.localhost is available too. Via webdev.yml you can define custom subdomains, for example for different languages or multi tenant systems.

How does it work?

Most of the work is done by traefik which takes care of all the routing and certificate generation. So you need to make sure that the service is enabled and running. The routes that traefik will handle, are defined via service labels. You may have already noticed a file called docker-compose.proxy.yml. This file will be generated by WebDev on startup and included via the devcontainer.json.

Service Labels

INFO

If you make changes to the service labels, for example changing the subdomain for a service, this service needs to be deleted and then recreated. This is a limitation of docker, once a container has been created, you can´t change their labels.

INFO

Never edit the docker-compose.proxy.yml file manually, it will be overwritten by WebDev

services:
  traefik:
    labels:
      traefik.enable: true
      traefik.http.routers.traefik.rule: Host(`traefik.devcontainer.dev.localhost`) || Host(`traefik.dev.localhost`)
      traefik.http.routers.traefik.entrypoints: https
      traefik.http.routers.traefik.tls: true
      traefik.http.routers.traefik.service: traefik@docker
      traefik.http.services.traefik.loadbalancer.server.port: 8080
  mysql:
    labels:
      traefik.enable: false
  mailpit:
    labels:
      traefik.enable: true
      traefik.http.routers.mailpit.rule: Host(`mail.devcontainer.dev.localhost`) || Host(`mail.dev.localhost`)
      traefik.http.routers.mailpit.entrypoints: https
      traefik.http.routers.mailpit.tls: true
      traefik.http.routers.mailpit.service: mailpit@docker
      traefik.http.services.mailpit.loadbalancer.server.port: 8025

This is an example of a generated docker-compose.proxy.yml. We can see we have three services. In the labels for traefik (line 4 to 9), we can see the label traefik.enable: true which tells traefik that this service should be accessable via traefik.devcontainer.dev.localhost and traefik.dev.localhost (line 5). In line 6, we can see that it should be made available via https and the port of the service is 8080. Looking at the mailpit service, we can see a similar definition, just with different ports and Host. The definition for mysql looks a bit different, since there is no public interface for it, so it will not be routed through traefik.

There are two config files involved in generating the proxy file with the service labels. First is the webdev.yml in which we define the domain and subdomain that should be used.

config:
  proxy:
    domain: dev.localhost
    subDomain: devcontainer

The value we define in domain is the one we also have to add to our hosts file to that all trafic will be routed to our container setup. You can leave the value for domain empty to use the default value dev.localhost. The subDomain is per default devcontainer but should be changed to your project name. So if your development environment is for project xyz, then you should set that as your subDomain too. It is not necessary but helps to keep everything clean.

The second file involved is the docker-compose.yml where we define the service we want to have available and also under which subDomain they should be accessable.

services:
  traefik:
    labels:
      com.webdev.proxy.subdomain: "traefik"
      com.webdev.proxy.port: "8080"

  mysql:
    labels:
      com.webdev.category: "database"
      com.webdev.name: "MySQL Server"
      com.webdev.description: "Relational Database"

  mailpit:
    labels:
      com.webdev.proxy.subdomain: "mail"
      com.webdev.proxy.port: "8025"

In this shortened version we can see that traefik has the labels com.webdev.proxy.subdomain and com.webdev.proxy.port. When these labels are set (note how the service mysql has no such labels), then we enable routing to this container. With com.webdev.proxy.subdomain we can define the subdomain for this service and with com.webdev.proxy.port the port of the service is defined.

So taking everything together, traefik is now accessable via traefik.devcontainer.dev.localhost from our webbrowser.

SSL Certificate

Since we want to replicate a production server, our application should also be available via https. Good thing that WebDev and traefik takes care of it without anything you need todo manually.

On startup, WebDev will check if a certificate already exists for this project(they can be found under .devcontainer/traefik/certs). If not, he will create a docker container (based on alpine/mkcert), which will then create the wildcard certificates. In the same process, he will also create the CA Certificate, which will be placed into ~/webdev/certs/. This can be imported into your local certificate registry, so that your browser will accept all certificates from your projects.