Commit 1316b9ca authored by David Danier's avatar David Danier
Browse files

README added

parent 81a467c9
# About
This is as very simple docker configuration to run traefik locally for simle
project handling. Traefik allows you to run multiple projects simultaneously
without open port collisions.
## More background
Normally when using docker you might end up for example using http://localhost:8000/
for accessing the web service of your configuration. This might be an apache server or
just a development server you use.
When starting multiple projects all needing to bind to localhost:8000 this will - of
course - fail. So you start constantly stopping projects for project switching.
Traefik is meant so solve this by providing a HTTP proxy which automatically changes
its own configuration whenever you spin up new docker containers. It then allows access
to the web frontends by just passing all requests through itself, only needing one
public port for all projects. To differentiate the projects it uses local domain names.
So for example:
* http://web.project1.local.t23dev/ could use the web server of project1
* http://web.someotherproject.local.t23dev/ could use the web server of someotherproject
# Install
Installing the traefik proxy is pretty simple, as it follows the normal b5 project
schema. So to get things up and running you just **need to have docker installed**
and then:
## Initial setup
```bash
b5 install
b5 update
```
## Running the project
```bash
b5 run
```
## Housekeeping
```bash
b5 update
```
# Your projects with traefik
To get your projects running with traefik I suggest the following schema:
* docker-compose.yml: Use this file to define all the services you need. DO NOT
open any ports here.
* docker-compose.localhost.yml: This file for opening the local ports, like
localhost:8000. This file can be used by anyone not caring about traefik and
should be the default configuration.
* docker-compose.traefik.yml: Neccessary changes to the configuration to get traefik
up and running. Basically adding the neccessary network and label options.
With b5 you should use `docker_compose_config_override` to choose the used additional
configuration file. This should default to 'localhost', developers might use local.yml
to change it to 'traefik'.
## Providing a local domain (.t23dev)
Traefik needs a local domain to differentiate the projects you use. The domain name
will make traefik choose the right backend container.
We use dnsmasq as a local nameservier for accomplishing that. Setup is as follows:
```shell
$ brew update # make sure we are up to date
$ brew install dnsmasq # install dnsmasq
$ cd $(brew --prefix) # cd into /usr/local
$ mkdir -p etc # make sure /usr/local/etc exists
$ echo 'address=/.t23dev/127.0.0.1' > etc/dnsmasq.conf # setup local dns resolving
$ sudo cp -v $(brew --prefix dnsmasq)/homebrew.mxcl.dnsmasq.plist /Library/LaunchDaemons # Enable dnsmasq daemon
$ sudo launchctl load -w /Library/LaunchDaemons/homebrew.mxcl.dnsmasq.plist # And start the daemon ;-)
$ sudo mkdir -p /etc/resolver # make sure /etc/resolver exists
$ sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/t23dev' # tell macOS to use the local dnsmasq nameserver for .t23dev
```
**Note:** The domain .t23dev shall be used for local development, see "T³P 0010 - Lokale Development Domains":
https://docs.google.com/document/d/1Pej_gE4yZVg0-vDY1azStgwHvq9J_oj-a4OrUbLpeSY/edit
## Example project configuration
### config.yml
```yaml
# This is the central configuration for all tools we use/execute. It is parsed inside
# the Taskfile, too. See $CONFIG_project_name for example.
project:
name: Example traefik project
key: traefik_example
url: http://www.doesnotexistyet.com/
paths:
web: ../web
modules:
# THIS is the important bit. Loading docker-compose.localhost.yml
docker:
docker_compose_config_override: localhost
```
### docker-compose.yml
**Note:** I use the official phpmyadmin container for this example, as it is ready to
use without any complex configuration (only one service, no volumes, …). For example
purposes I skipped the neccessary MySQL server.
```yaml
version: '3'
services:
phpmyadmin:
image: phpmyadmin/phpmyadmin
```
### docker-compose.localhost.yml
In this file we open the normal ports for localhost:PORT usage. As a convention
we use port 8001 for phpmyadmin.
```yaml
version: '3'
services:
phpmyadmin:
ports:
- "8001:80"
```
### docker-compose.traefik.yml
Now we add the configuration necessary for traefik to pick up the service and
provide the proxy services we want.
See https://docs.traefik.io/configuration/backends/docker/#labels-overriding-default-behaviour
for a full documentation of the possible labels you might use.
```yaml
version: '3'
services:
phpmyadmin:
# Make sure the service is inside the default network to access for example
# mysql and the traefik gateway network to allow traefik accessing it.
networks:
- default
- traefik_gateway
# These labels are read by traefik for service configuration
labels:
# Enable traefik proxy
- traefik.enable=true
# Ensure traefik uses the right network
- traefik.docker.network=traefik_gateway
# It might be neccessary to point traefik to the correct port of the
# service
#- traefik.port=8000
solr:
networks:
# This is the normal default network
default:
# In addition we need to add the traefik network as external
# (This also means traefik has to be started BEFORE your project)
traefik_gateway:
external: true
```
\ No newline at end of file
......@@ -6,4 +6,4 @@ project:
paths:
modules:
docker:
docker_compose_config_override: localhost
version: '3'
services:
traefik:
ports:
- "80:80"
- "8080:8080"
networks:
gateway:
......@@ -5,9 +5,6 @@ services:
image: traefik
networks:
- gateway
ports:
- "80:80"
- "8080:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./traefik.toml:/traefik.toml
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment