From 17afa3e6729b014da8214b145b7c0aea4ea37612 Mon Sep 17 00:00:00 2001 From: Emile Vauge Date: Fri, 15 Apr 2016 16:27:40 +0200 Subject: [PATCH] Add doc user guide with swarm Signed-off-by: Emile Vauge --- docs/css/traefik.css | 18 ++++ docs/toml.md | 141 ++++++------------------------ docs/user-guide/examples.md | 98 +++++++++++++++++++++ docs/user-guide/swarm.md | 170 ++++++++++++++++++++++++++++++++++++ mkdocs.yml | 3 + 5 files changed, 317 insertions(+), 113 deletions(-) create mode 100644 docs/user-guide/examples.md create mode 100644 docs/user-guide/swarm.md diff --git a/docs/css/traefik.css b/docs/css/traefik.css index 051a0b486..7c0431e9e 100644 --- a/docs/css/traefik.css +++ b/docs/css/traefik.css @@ -40,4 +40,22 @@ h1, h2, h3, H4 { blockquote p { font-size: 14px; +} + +.navbar-default .navbar-nav>.open>a, .navbar-default .navbar-nav>.open>a:hover, .navbar-default .navbar-nav>.open>a:focus { + color: #fff; + background-color: #25606F; +} + +.dropdown-menu>li>a:hover, .dropdown-menu>li>a:focus { + color: #fff; + text-decoration: none; + background-color: #25606F; +} + +.dropdown-menu>.active>a, .dropdown-menu>.active>a:hover, .dropdown-menu>.active>a:focus { + color: #fff; + text-decoration: none; + background-color: #25606F; + outline: 0; } \ No newline at end of file diff --git a/docs/toml.md b/docs/toml.md index 8fc0c233b..58aaf5804 100644 --- a/docs/toml.md +++ b/docs/toml.md @@ -89,6 +89,10 @@ # [entryPoints.http.redirect] # regex = "^http://localhost/(.*)" # replacement = "http://mydomain/$1" + +entryPoints] + [entryPoints.http] + address = ":80" ``` ## Retry configuration @@ -98,7 +102,7 @@ # # Optional # -# [retry] +[retry] # Number of attempts # @@ -122,27 +126,27 @@ # # Optional # -# [acme] +[acme] # Email address used for registration # # Required # -# email = "test@traefik.io" +email = "test@traefik.io" # File used for certificates storage. # WARNING, if you use Traefik in Docker, don't forget to mount this file as a volume. # # Required # -# storageFile = "acme.json" +storageFile = "acme.json" # Entrypoint to proxy acme challenge to. # WARNING, must point to an entrypoint on port 443 # # Required # -# entryPoint = "https" +entryPoint = "https" # Enable on demand certificate. This will request a certificate from Let's Encrypt during the first TLS handshake for a hostname that does not yet have a certificate. # WARNING, TLS handshakes will be slow when requesting a hostname certificate for the first time, this can leads to DoS attacks. @@ -175,6 +179,13 @@ # main = "local3.com" # [[acme.domains]] # main = "local4.com" +[[acme.domains]] + main = "local1.com" + sans = ["test1.local1.com", "test2.local1.com"] +[[acme.domains]] + main = "local3.com" +[[acme.domains]] + main = "local4.com" ``` # Configuration backends @@ -716,25 +727,25 @@ Træfɪk can be configured to use Etcd as a backend configuration: # # Optional # -# [etcd] +[etcd] # Etcd server endpoint # # Required # -# endpoint = "127.0.0.1:4001" +endpoint = "127.0.0.1:4001" # Enable watch Etcd changes # # Optional # -# watch = true +watch = true # Prefix used for KV store. # # Optional # -# prefix = "/traefik" +prefix = "/traefik" # Override default configuration template. For advanced users :) # @@ -769,25 +780,25 @@ Træfɪk can be configured to use Zookeeper as a backend configuration: # # Optional # -# [zookeeper] +[zookeeper] # Zookeeper server endpoint # # Required # -# endpoint = "127.0.0.1:2181" +endpoint = "127.0.0.1:2181" # Enable watch Zookeeper changes # # Optional # -# watch = true +watch = true # Prefix used for KV store. # # Optional # -# prefix = "/traefik" +prefix = "/traefik" # Override default configuration template. For advanced users :) # @@ -811,25 +822,25 @@ Træfɪk can be configured to use BoltDB as a backend configuration: # # Optional # -# [boltdb] +[boltdb] # BoltDB file # # Required # -# endpoint = "/my.db" +endpoint = "/my.db" # Enable watch BoltDB changes # # Optional # -# watch = true +watch = true # Prefix used for KV store. # # Optional # -# prefix = "/traefik" +prefix = "/traefik" # Override default configuration template. For advanced users :) # @@ -920,99 +931,3 @@ Once the `/traefik/alias` key is updated, the new `/traefik_configurations/2` co Note that Træfɪk *will not watch for key changes in the `/traefik_configurations` prefix*. It will only watch for changes in the `/traefik` prefix. Further, if the `/traefik/alias` key is set, all other sibling keys with the `/traefik` prefix are ignored. - -# Examples - -## HTTP only - -``` -defaultEntryPoints = ["http"] -[entryPoints] - [entryPoints.http] - address = ":80" -``` - -## HTTP + HTTPS (with SNI) - -``` -defaultEntryPoints = ["http", "https"] -[entryPoints] - [entryPoints.http] - address = ":80" - [entryPoints.https] - address = ":443" - [entryPoints.https.tls] - [[entryPoints.https.tls.certificates]] - CertFile = "integration/fixtures/https/snitest.com.cert" - KeyFile = "integration/fixtures/https/snitest.com.key" - [[entryPoints.https.tls.certificates]] - CertFile = "integration/fixtures/https/snitest.org.cert" - KeyFile = "integration/fixtures/https/snitest.org.key" -``` - -## HTTP redirect on HTTPS - -``` -defaultEntryPoints = ["http", "https"] -[entryPoints] - [entryPoints.http] - address = ":80" - [entryPoints.http.redirect] - entryPoint = "https" - [entryPoints.https] - address = ":443" - [entryPoints.https.tls] - [[entryPoints.https.tls.certificates]] - certFile = "tests/traefik.crt" - keyFile = "tests/traefik.key" -``` - -## Let's Encrypt support - -``` -[entryPoints] - [entryPoints.https] - address = ":443" - [entryPoints.https.tls] - # certs used as default certs - [[entryPoints.https.tls.certificates]] - certFile = "tests/traefik.crt" - keyFile = "tests/traefik.key" -[acme] -email = "test@traefik.io" -storageFile = "acme.json" -onDemand = true -caServer = "http://172.18.0.1:4000/directory" -entryPoint = "https" - -[[acme.domains]] - main = "local1.com" - sans = ["test1.local1.com", "test2.local1.com"] -[[acme.domains]] - main = "local2.com" - sans = ["test1.local2.com", "test2x.local2.com"] -[[acme.domains]] - main = "local3.com" -[[acme.domains]] - main = "local4.com" -``` - -## Override entrypoints in frontends - -``` -[frontends] - [frontends.frontend1] - backend = "backend2" - [frontends.frontend1.routes.test_1] - rule = "Host:test.localhost" - [frontends.frontend2] - backend = "backend1" - passHostHeader = true - entrypoints = ["https"] # overrides defaultEntryPoints - [frontends.frontend2.routes.test_1] - rule = "Host:{subdomain:[a-z]+}.localhost" - [frontends.frontend3] - entrypoints = ["http", "https"] # overrides defaultEntryPoints - backend = "backend2" - rule = "Path:/test" -``` diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md new file mode 100644 index 000000000..cf164755c --- /dev/null +++ b/docs/user-guide/examples.md @@ -0,0 +1,98 @@ + +# Examples + +You will find here some configuration examples of Træfɪk. + +## HTTP only + +``` +defaultEntryPoints = ["http"] +[entryPoints] + [entryPoints.http] + address = ":80" +``` + +## HTTP + HTTPS (with SNI) + +``` +defaultEntryPoints = ["http", "https"] +[entryPoints] + [entryPoints.http] + address = ":80" + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + [[entryPoints.https.tls.certificates]] + CertFile = "integration/fixtures/https/snitest.com.cert" + KeyFile = "integration/fixtures/https/snitest.com.key" + [[entryPoints.https.tls.certificates]] + CertFile = "integration/fixtures/https/snitest.org.cert" + KeyFile = "integration/fixtures/https/snitest.org.key" +``` + +## HTTP redirect on HTTPS + +``` +defaultEntryPoints = ["http", "https"] +[entryPoints] + [entryPoints.http] + address = ":80" + [entryPoints.http.redirect] + entryPoint = "https" + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + [[entryPoints.https.tls.certificates]] + certFile = "tests/traefik.crt" + keyFile = "tests/traefik.key" +``` + +## Let's Encrypt support + +``` +[entryPoints] + [entryPoints.https] + address = ":443" + [entryPoints.https.tls] + # certs used as default certs + [[entryPoints.https.tls.certificates]] + certFile = "tests/traefik.crt" + keyFile = "tests/traefik.key" +[acme] +email = "test@traefik.io" +storageFile = "acme.json" +onDemand = true +caServer = "http://172.18.0.1:4000/directory" +entryPoint = "https" + +[[acme.domains]] + main = "local1.com" + sans = ["test1.local1.com", "test2.local1.com"] +[[acme.domains]] + main = "local2.com" + sans = ["test1.local2.com", "test2x.local2.com"] +[[acme.domains]] + main = "local3.com" +[[acme.domains]] + main = "local4.com" +``` + +## Override entrypoints in frontends + +``` +[frontends] + [frontends.frontend1] + backend = "backend2" + [frontends.frontend1.routes.test_1] + rule = "Host:test.localhost" + [frontends.frontend2] + backend = "backend1" + passHostHeader = true + entrypoints = ["https"] # overrides defaultEntryPoints + [frontends.frontend2.routes.test_1] + rule = "Host:{subdomain:[a-z]+}.localhost" + [frontends.frontend3] + entrypoints = ["http", "https"] # overrides defaultEntryPoints + backend = "backend2" + rule = "Path:/test" +``` diff --git a/docs/user-guide/swarm.md b/docs/user-guide/swarm.md new file mode 100644 index 000000000..5a720fccf --- /dev/null +++ b/docs/user-guide/swarm.md @@ -0,0 +1,170 @@ +# Swarm cluster + +This section explains how to create a multi-host [swarm](https://docs.docker.com/swarm) cluster using [docker-machine](https://docs.docker.com/machine/) and how to deploy Træfɪk on it. +The cluster will be made of: + +- 2 servers +- 1 swarm master +- 2 swarm nodes +- 1 [overlay](https://docs.docker.com/engine/userguide/networking/dockernetworks/#an-overlay-network) network (multi-host networking) + +## Prerequisites + +1. You will need to install [docker-machine](https://docs.docker.com/machine/) +2. You will need the latest [VirtualBox](https://www.virtualbox.org/wiki/Downloads) + +## Cluster provisioning + +We will first follow [this guide](https://docs.docker.com/engine/userguide/networking/get-started-overlay/) to create the cluster. + +### Create machine `mh-keystore` + +This machine will be the service registry of our cluster. + +```sh +docker-machine create -d virtualbox mh-keystore +``` + +Then we install the service registry [Consul](https://consul.io) on this machine: + +```sh +eval "$(docker-machine env mh-keystore)" +docker run -d \ + -p "8500:8500" \ + -h "consul" \ + progrium/consul -server -bootstrap +``` + +### Create machine `mhs-demo0` + +This machine will have a swarm master and a swarm agent on it. + +```sh +docker-machine create -d virtualbox \ + --swarm --swarm-master \ + --swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \ + --engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \ + --engine-opt="cluster-advertise=eth1:2376" \ + mhs-demo0 +``` + +### Create machine `mhs-demo1` + +This machine will have a swarm agent on it. + +```sh +docker-machine create -d virtualbox \ + --swarm \ + --swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \ + --engine-opt="cluster-store=consul://$(docker-machine ip mh-keystore):8500" \ + --engine-opt="cluster-advertise=eth1:2376" \ + mhs-demo1 +``` + +### Create the overlay Network + +Create the overlay network on the swarm master: + +```sh +eval $(docker-machine env --swarm mhs-demo0) +docker network create --driver overlay --subnet=10.0.9.0/24 my-net +``` + +## Deploy Træfɪk + +Deploy Træfɪk: + +```sh +docker $(docker-machine config mhs-demo0) run \ + -d \ + -p 80:80 -p 8080:8080 \ + --net=my-net \ + -v /var/lib/boot2docker/:/ssl \ + traefik \ + -l DEBUG \ + -c /dev/null \ + --docker \ + --docker.domain traefik \ + --docker.endpoint tcp://$(docker-machine ip mhs-demo0):3376 \ + --docker.tls \ + --docker.tls.ca /ssl/ca.pem \ + --docker.tls.cert /ssl/server.pem \ + --docker.tls.key /ssl/server-key.pem \ + --docker.tls.insecureSkipVerify \ + --docker.watch \ + --web +``` + +Let's explain this command: + +- `-p 80:80 -p 8080:8080`: we bind ports 80 and 8080 +- `--net=my-net`: run the container on the network my-net +- `-v /var/lib/boot2docker/:/ssl`: mount the ssl keys generated by docker-machine +- `-c /dev/null`: empty config file +- `--docker`: enable docker backend +- `--docker.endpoint tcp://172.18.0.1:3376`: connect to the swarm master using the docker_gwbridge network +- `--docker.tls`: enable TLS using the docker-machine keys +- `--web`: activate the webUI on port 8080 + +## Deploy your apps + +We can now deploy our app on the cluster, here [whoami](https://github.com/emilevauge/whoami), a simple web server in GO, on the network `my-net`: + +```sh +eval $(docker-machine env --swarm mhs-demo0) +docker run -d --name=whoami0 --net=my-net --env="constraint:node==mhs-demo0" emilevauge/whoami +docker run -d --name=whoami1 --net=my-net --env="constraint:node==mhs-demo1" emilevauge/whoami +``` + +Check that everything is started: + +```sh +docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +ba2c21488299 emilevauge/whoami "/whoamI" 8 seconds ago Up 9 seconds 80/tcp mhs-demo1/whoami1 +8147a7746e7a emilevauge/whoami "/whoamI" 19 seconds ago Up 20 seconds 80/tcp mhs-demo0/whoami0 +8fbc39271b4c traefik "/traefik -l DEBUG -c" 36 seconds ago Up 37 seconds 192.168.99.101:80->80/tcp, 192.168.99.101:8080->8080/tcp mhs-demo0/serene_bhabha +``` + +## Access to your apps through Træfɪk + +```sh +curl -H Host:whoami0.traefik http://$(docker-machine ip mhs-demo0) +Hostname: 8147a7746e7a +IP: 127.0.0.1 +IP: ::1 +IP: 10.0.9.3 +IP: fe80::42:aff:fe00:903 +IP: 172.18.0.3 +IP: fe80::42:acff:fe12:3 +GET / HTTP/1.1 +Host: 10.0.9.3:80 +User-Agent: curl/7.35.0 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 192.168.99.1 +X-Forwarded-Host: 10.0.9.3:80 +X-Forwarded-Proto: http +X-Forwarded-Server: 8fbc39271b4c + +curl -H Host:whoami1.traefik http://$(docker-machine ip mhs-demo0) +Hostname: ba2c21488299 +IP: 127.0.0.1 +IP: ::1 +IP: 10.0.9.4 +IP: fe80::42:aff:fe00:904 +IP: 172.18.0.2 +IP: fe80::42:acff:fe12:2 +GET / HTTP/1.1 +Host: 10.0.9.4:80 +User-Agent: curl/7.35.0 +Accept: */* +Accept-Encoding: gzip +X-Forwarded-For: 192.168.99.1 +X-Forwarded-Host: 10.0.9.4:80 +X-Forwarded-Proto: http +X-Forwarded-Server: 8fbc39271b4c +``` + +![](http://i.giphy.com/ujUdrdpX7Ok5W.gif) + diff --git a/mkdocs.yml b/mkdocs.yml index 88a867542..3eb8ffccb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,4 +46,7 @@ pages: - Getting Started: index.md - Basics: basics.md - traefik.toml: toml.md + - User Guide: + - 'Configuration examples': 'user-guide/examples.md' + - 'Swarm cluster': 'user-guide/swarm.md' - Benchmarks: benchmarks.md \ No newline at end of file