From b9af55fc49f2f71ceccef9c2b7a06a93aa443411 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9rald=20Cro=C3=ABs?= Date: Thu, 22 Mar 2018 12:34:03 +0100 Subject: [PATCH] Introduction update --- README.md | 215 +++++++++--------- docs/index.md | 287 ++++++++++++------------- examples/quickstart/README.md | 106 +++++++++ examples/quickstart/docker-compose.yml | 18 ++ 4 files changed, 367 insertions(+), 259 deletions(-) create mode 100644 examples/quickstart/README.md create mode 100644 examples/quickstart/docker-compose.yml diff --git a/README.md b/README.md index 2ff4947ed..7a910885e 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,9 @@ [![Twitter](https://img.shields.io/twitter/follow/traefikproxy.svg?style=social)](https://twitter.com/intent/follow?screen_name=traefikproxy) -Træfik (pronounced like _traffic_) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. -It supports several backends ([Docker](https://www.docker.com/), [Swarm mode](https://docs.docker.com/engine/swarm/), [Kubernetes](https://kubernetes.io), [Marathon](https://mesosphere.github.io/marathon/), [Consul](https://www.consul.io/), [Etcd](https://coreos.com/etcd/), [Rancher](https://rancher.com), [Amazon ECS](https://aws.amazon.com/ecs), and a lot more) to manage its configuration automatically and dynamically. +Træfik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy. +Træfik integrates with your existing infrastructure components ([Docker](https://www.docker.com/), [Swarm mode](https://docs.docker.com/engine/swarm/), [Kubernetes](https://kubernetes.io), [Marathon](https://mesosphere.github.io/marathon/), [Consul](https://www.consul.io/), [Etcd](https://coreos.com/etcd/), [Rancher](https://rancher.com), [Amazon ECS](https://aws.amazon.com/ecs), ...) and configures itself automatically and dynamically. +Telling Træfik where your orchestrator is could be the _only_ configuration step you need to do. --- @@ -36,60 +37,101 @@ It supports several backends ([Docker](https://www.docker.com/), [Swarm mode](ht ## Overview -Imagine that you have deployed a bunch of microservices on your infrastructure. You probably used a service registry (like etcd or consul) and/or an orchestrator (swarm, Mesos/Marathon) to manage all these services. -If you want your users to access some of your microservices from the Internet, you will have to use a reverse proxy and configure it using virtual hosts or prefix paths: +Imagine that you have deployed a bunch of microservices with the help of an orchestrator (like Swarm or Kubernetes) or a service registry (like etcd or consul). +Now you want users to access these microservices, and you need a reverse proxy. -- domain `api.domain.com` will point the microservice `api` in your private network -- path `domain.com/web` will point the microservice `web` in your private network -- domain `backoffice.domain.com` will point the microservices `backoffice` in your private network, load-balancing between your multiple instances +Traditional reverse-proxies require that you configure _each_ route that will connect paths and subdomains to _each_ microservice. +In an environment where you add, remove, kill, upgrade, or scale your services _many_ times a day, the task of keeping the routes up to date becomes tedious. -Microservices are often deployed in dynamic environments where services are added, removed, killed, upgraded or scaled many times a day. +**This is when Træfik can help you!** -Traditional reverse-proxies are not natively dynamic. You can't change their configuration and hot-reload easily. +Træfik listens to your service registry/orchestrator API and instantly generates the routes so your microservices are connected to the outside world -- without further intervention from your part. -Here enters Træfik. +**Run Træfik and let it do the work for you!** +_(But if you'd rather configure some of your routes manually, Træfik supports that too!)_ ![Architecture](docs/img/architecture.png) -Træfik can listen to your service registry/orchestrator API, and knows each time a microservice is added, removed, killed or upgraded, and can generate its configuration automatically. -Routes to your services will be created instantly. - -Run it and forget it! - - ## Features -- [It's fast](https://docs.traefik.io/benchmarks) -- No dependency hell, single binary made with go -- [Tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image -- Rest API -- Hot-reloading of configuration. No need to restart the process +- Continuously updates its configuration (No restarts!) +- Supports multiple load balancing algorithms +- Provides HTTPS to your microservices by leveraging [Let's Encrypt](https://letsencrypt.org) - Circuit breakers, retry -- Round Robin, rebalancer load-balancers -- Metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB) -- Clean AngularJS Web UI -- Websocket, HTTP/2, GRPC ready -- Access Logs (JSON, CLF) -- [Let's Encrypt](https://letsencrypt.org) support (Automatic HTTPS with renewal) -- [Proxy Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) support - High Availability with cluster mode (beta) +- See the magic through its clean web UI +- Websocket, HTTP/2, GRPC ready +- Provides metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB) +- Keeps access logs (JSON, CLF) +- [Fast](https://docs.traefik.io/benchmarks) ... which is nice +- Exposes a Rest API +- Packaged as a single binary file (made with :heart: with go) and available as a [tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image -## Supported backends -- [Docker](https://www.docker.com/) / [Swarm mode](https://docs.docker.com/engine/swarm/) -- [Kubernetes](https://kubernetes.io) -- [Mesos](https://github.com/apache/mesos) / [Marathon](https://mesosphere.github.io/marathon/) -- [Rancher](https://rancher.com) (API, Metadata) -- [Consul](https://www.consul.io/) / [Etcd](https://coreos.com/etcd/) / [Zookeeper](https://zookeeper.apache.org) / [BoltDB](https://github.com/boltdb/bolt) -- [Eureka](https://github.com/Netflix/eureka) -- [Amazon ECS](https://aws.amazon.com/ecs) -- [Amazon DynamoDB](https://aws.amazon.com/dynamodb) -- File -- Rest API +## Supported Backends + +- [Docker](docs/configuration/backends/docker/) / [Swarm mode](docs/configuration/backends/docker/#docker-swarm-mode) +- [Kubernetes](docs/configuration/backends/kubernetes/) +- [Mesos](docs/configuration/backends/mesos/) / [Marathon](docs/configuration/backends/marathon/) +- [Rancher](docs/configuration/backends/rancher/) (API, Metadata) +- [Service Fabric](docs/configuration/backends/servicefabric/) +- [Consul Catalog](docs/configuration/backends/consulcatalog/) +- [Consul](docs/configuration/backends/consul/) / [Etcd](docs/configuration/backends/etcd/) / [Zookeeper](docs/configuration/backends/zookeeper/) / [BoltDB](docs/configuration/backends/boltdb/) +- [Eureka](docs/configuration/backends/eureka/) +- [Amazon ECS](docs/configuration/backends/ecs/) +- [Amazon DynamoDB](docs/configuration/backends/dynamodb/) +- [File](docs/configuration/backends/file/) +- [Rest](docs/configuration/backends/rest/) ## Quickstart -You can have a quick look at Træfik in this [Katacoda tutorial](https://www.katacoda.com/courses/traefik/deploy-load-balancer) that shows how to load balance requests between multiple Docker containers. If you are looking for a more comprehensive and real use-case example, you can also check [Play-With-Docker](http://training.play-with-docker.com/traefik-load-balancing/) to see how to load balance between multiple nodes. +To get your hands on Træfik, you can use the [5-Minute Quickstart](http://docs.traefik.io/#the-trfik-quickstart-using-docker) in our documentation (you will need Docker). + +Alternatively, if you don't want to install anything on your computer, you can try Træfik online in this great [Katacoda tutorial](https://www.katacoda.com/courses/traefik/deploy-load-balancer) that shows how to load balance requests between multiple Docker containers. + +If you are looking for a more comprehensive and real use-case example, you can also check [Play-With-Docker](http://training.play-with-docker.com/traefik-load-balancing/) to see how to load balance between multiple nodes. + +## Web UI + +You can access the simple HTML frontend of Træfik. + +![Web UI Providers](docs/img/web.frontend.png) +![Web UI Health](docs/img/traefik-health.png) + +## Documentation + +You can find the complete documentation at [https://docs.traefik.io](https://docs.traefik.io). +A collection of contributions around Træfik can be found at [https://awesome.traefik.io](https://awesome.traefik.io). + +## Support + +To get community support, you can: +- join the Træfik community Slack channel: [![Join the chat at https://traefik.herokuapp.com](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://traefik.herokuapp.com) +- use [Stack Overflow](https://stackoverflow.com/questions/tagged/traefik) (using the `traefik` tag) + +If you need commercial support, please contact [Containo.us](https://containo.us) by mail: . + +## Download + +- Grab the latest binary from the [releases](https://github.com/containous/traefik/releases) page and run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): + +```shell +./traefik --configFile=traefik.toml +``` + +- Or use the official tiny Docker image and run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): + +```shell +docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik +``` + +- Or get the sources: + +```shell +git clone https://github.com/containous/traefik +``` + +## Introductory Videos Here is a talk given by [Emile Vauge](https://github.com/emilevauge) at [GopherCon 2017](https://gophercon.com/). You will learn Træfik basics in less than 10 minutes. @@ -101,81 +143,26 @@ You will learn fundamental Træfik features and see some demos with Kubernetes. [![Traefik ContainerCamp UK](https://img.youtube.com/vi/aFtpIShV60I/0.jpg)](https://www.youtube.com/watch?v=aFtpIShV60I) - -## Web UI - -You can access the simple HTML frontend of Træfik. - -![Web UI Providers](docs/img/web.frontend.png) -![Web UI Health](docs/img/traefik-health.png) - - -## Test it - -- The simple way: grab the latest binary from the [releases](https://github.com/containous/traefik/releases) page and just run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): - -```shell -./traefik --configFile=traefik.toml -``` - -- Use the tiny Docker image and just run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): - -```shell -docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik -``` - -- From sources: - -```shell -git clone https://github.com/containous/traefik -``` - - -## Documentation - -You can find the complete documentation at [https://docs.traefik.io](https://docs.traefik.io). -A collection of contributions around Træfik can be found at [https://awesome.traefik.io](https://awesome.traefik.io). - - -## Support - -To get basic support, you can: -- join the Træfik community Slack channel: [![Join the chat at https://traefik.herokuapp.com](https://img.shields.io/badge/style-register-green.svg?style=social&label=Slack)](https://traefik.herokuapp.com) -- use [Stack Overflow](https://stackoverflow.com/questions/tagged/traefik) (using the `traefik` tag) - -If you prefer commercial support, please contact [containo.us](https://containo.us) by mail: . - - -## Release cycle - -- Release: We try to release a new version every 2 months - - i.e.: 1.3.0, 1.4.0, 1.5.0 -- Release candidate: we do RC (1.**x**.0-rc**y**) before the final release (1.**x**.0) - - i.e.: 1.1.0-rc1 -> 1.1.0-rc2 -> 1.1.0-rc3 -> 1.1.0-rc4 -> 1.1.0 -- Bug-fixes: For each version we release bug fixes - - i.e.: 1.1.1, 1.1.2, 1.1.3 - - those versions contain only bug-fixes - - no additional features are delivered in those versions -- Each version is supported until the next one is released - - i.e.: 1.1.x will be supported until 1.2.0 is out -- We use [Semantic Versioning](http://semver.org/) - - -## Contributing - -Please refer to [contributing documentation](CONTRIBUTING.md). - - -### Code of Conduct - -Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). -By participating in this project you agree to abide by its terms. - - ## Maintainers [Information about process and maintainers](MAINTAINER.md) +## Contributing + +If you'd like to contribute to the project, refer to the [contributing documentation](CONTRIBUTING.md). + +Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). +By participating in this project, you agree to abide by its terms. + +## Release Cycle + +- We release a new version (e.g. 1.1.0, 1.2.0, 1.3.0) every other month. +- Release Candidates are available before the release (e.g. 1.1.0-rc1, 1.1.0-rc2, 1.1.0-rc3, 1.1.0-rc4, before 1.1.0) +- Bug-fixes (e.g. 1.1.1, 1.1.2, 1.2.1, 1.2.3) are released as needed (no additional features are delivered in those versions, bug-fixes only) + +Each version is supported until the next one is released (e.g. 1.1.x will be supported until 1.2.0 is out) + +We use [Semantic Versioning](http://semver.org/) ## Plumbing @@ -184,11 +171,11 @@ By participating in this project you agree to abide by its terms. - [Negroni](https://github.com/urfave/negroni): web middlewares made simple - [Lego](https://github.com/xenolf/lego): the best [Let's Encrypt](https://letsencrypt.org) library in go - ## Credits Kudos to [Peka](http://peka.byethost11.com/photoblog/) for his awesome work on the logo ![logo](docs/img/traefik.icon.png). -Traefik's logo licensed under the Creative Commons 3.0 Attributions license. + +Traefik's logo is licensed under the Creative Commons 3.0 Attributions license. Traefik's logo was inspired by the gopher stickers made by Takuya Ueda (https://twitter.com/tenntenn). -The original Go gopher was designed by Renee French (http://reneefrench.blogspot.com/). +The original Go gopher was designed by Renee French (http://reneefrench.blogspot.com/). \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index cb883342a..00d2c30d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,65 +10,165 @@ [![Twitter](https://img.shields.io/twitter/follow/traefikproxy.svg?style=social)](https://twitter.com/intent/follow?screen_name=traefikproxy) -Træfik (pronounced like _traffic_) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. -It supports several backends ([Docker](https://www.docker.com/), [Swarm mode](https://docs.docker.com/engine/swarm/), [Kubernetes](https://kubernetes.io), [Marathon](https://mesosphere.github.io/marathon/), [Consul](https://www.consul.io/), [Etcd](https://coreos.com/etcd/), [Rancher](https://rancher.com), [Amazon ECS](https://aws.amazon.com/ecs), and a lot more) to manage its configuration automatically and dynamically. +Træfik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy. +Træfik integrates with your existing infrastructure components ([Docker](https://www.docker.com/), [Swarm mode](https://docs.docker.com/engine/swarm/), [Kubernetes](https://kubernetes.io), [Marathon](https://mesosphere.github.io/marathon/), [Consul](https://www.consul.io/), [Etcd](https://coreos.com/etcd/), [Rancher](https://rancher.com), [Amazon ECS](https://aws.amazon.com/ecs), ...) and configures itself automatically and dynamically. +Telling Træfik where your orchestrator is could be the _only_ configuration step you need to do. ## Overview -Imagine that you have deployed a bunch of microservices on your infrastructure. You probably used a service registry (like etcd or consul) and/or an orchestrator (swarm, Mesos/Marathon) to manage all these services. -If you want your users to access some of your microservices from the Internet, you will have to use a reverse proxy and configure it using virtual hosts or prefix paths: +Imagine that you have deployed a bunch of microservices with the help of an orchestrator (like Swarm or Kubernetes) or a service registry (like etcd or consul). +Now you want users to access these microservices, and you need a reverse proxy. -- domain `api.domain.com` will point the microservice `api` in your private network -- path `domain.com/web` will point the microservice `web` in your private network -- domain `backoffice.domain.com` will point the microservices `backoffice` in your private network, load-balancing between your multiple instances +Traditional reverse-proxies require that you configure _each_ route that will connect paths and subdomains to _each_ microservice. In an environment where you add, remove, kill, upgrade, or scale your services _many_ times a day, the task of keeping the routes up to date becomes tedious. -Microservices are often deployed in dynamic environments where services are added, removed, killed, upgraded or scaled many times a day. +**This is when Træfik can help you!** -Traditional reverse-proxies are not natively dynamic. You can't change their configuration and hot-reload easily. +Træfik listens to your service registry/orchestrator API and instantly generates the routes so your microservices are connected to the outside world -- without further intervention from your part. -Here enters Træfik. +**Run Træfik and let it do the work for you!** +_(But if you'd rather configure some of your routes manually, Træfik supports that too!)_ ![Architecture](img/architecture.png) -Træfik can listen to your service registry/orchestrator API, and knows each time a microservice is added, removed, killed or upgraded, and can generate its configuration automatically. -Routes to your services will be created instantly. - -Run it and forget it! - ## Features -- [It's fast](/benchmarks) -- No dependency hell, single binary made with go -- [Tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image -- Rest API -- Hot-reloading of configuration. No need to restart the process +- Continuously updates its configuration (No restarts!) +- Supports multiple load balancing algorithms +- Provides HTTPS to your microservices by leveraging [Let's Encrypt](https://letsencrypt.org) - Circuit breakers, retry -- Round Robin, rebalancer load-balancers -- Metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB) -- Clean AngularJS Web UI +- High Availability with cluster mode (beta) +- See the magic through its clean web UI - Websocket, HTTP/2, GRPC ready -- Access Logs (JSON, CLF) -- [Let's Encrypt](https://letsencrypt.org) support (Automatic HTTPS with renewal) -- High Availability with cluster mode +- Provides metrics (Rest, Prometheus, Datadog, Statsd, InfluxDB) +- Keeps access logs (JSON, CLF) +- [Fast](/benchmarks) ... which is nice +- Exposes a Rest API +- Packaged as a single binary file (made with :heart: with go) and available as a [tiny](https://microbadger.com/images/traefik) [official](https://hub.docker.com/r/_/traefik/) docker image ## Supported backends -- [Docker](https://www.docker.com/) / [Swarm mode](https://docs.docker.com/engine/swarm/) -- [Kubernetes](https://kubernetes.io) -- [Mesos](https://github.com/apache/mesos) / [Marathon](https://mesosphere.github.io/marathon/) -- [Rancher](https://rancher.com) (API, Metadata) -- [Consul](https://www.consul.io/) / [Etcd](https://coreos.com/etcd/) / [Zookeeper](https://zookeeper.apache.org) / [BoltDB](https://github.com/boltdb/bolt) -- [Eureka](https://github.com/Netflix/eureka) -- [Amazon ECS](https://aws.amazon.com/ecs) -- [Amazon DynamoDB](https://aws.amazon.com/dynamodb) -- File -- Rest API +- [Docker](/configuration/backends/docker/) / [Swarm mode](/configuration/backends/docker/#docker-swarm-mode) +- [Kubernetes](/configuration/backends/kubernetes/) +- [Mesos](/configuration/backends/mesos/) / [Marathon](/configuration/backends/marathon/) +- [Rancher](/configuration/backends/rancher/) (API, Metadata) +- [Service Fabric](/configuration/backends/servicefabric/) +- [Consul Catalog](/configuration/backends/consulcatalog/) +- [Consul](/configuration/backends/consul/) / [Etcd](/configuration/backends/etcd/) / [Zookeeper](/configuration/backends/zookeeper/) / [BoltDB](/configuration/backends/boltdb/) +- [Eureka](/configuration/backends/eureka/) +- [Amazon ECS](/configuration/backends/ecs/) +- [Amazon DynamoDB](/configuration/backends/dynamodb/) +- [File](/configuration/backends/file/) +- [Rest](/configuration/backends/rest/) +## The Træfik Quickstart (Using Docker) -## Quickstart +In this quickstart, we'll use [Docker compose](https://docs.docker.com/compose) to create our demo infrastructure. -You can have a quick look at Træfik in this [Katacoda tutorial](https://www.katacoda.com/courses/traefik/deploy-load-balancer) that shows how to load balance requests between multiple Docker containers. +To save some time, you can clone [Træfik's repository](https://github.com/containous/traefik) and use the quickstart files located in the [examples/quickstart](https://github.com/containous/traefik/tree/master/examples/quickstart/) directory. + +### 1 — Launch Træfik — Tell It to Listen to Docker + +Create a `docker-compose.yml` file where you will define a `reverse-proxy` service that uses the official Træfik image: + +```yaml +version: '3' + +services: + reverse-proxy: + image: traefik #The official Traefik docker image + command: --api --docker #Enables the web UI and tells Træfik to listen to docker + ports: + - "80:80" #The HTTP port + - "8080:8080" #The Web UI (enabled by --api) + volumes: + - /var/run/docker.sock:/var/run/docker.sock #So that Traefik can listen to the Docker events +``` + +**That's it. Now you can launch Træfik!** + +Start your `reverse-proxy` with the following command: + +```shell +docker-compose up -d reverse-proxy +``` + +You can open a browser and go to [http://localhost:8080](http://localhost:8080) to see Træfik's dashboard (we'll go back there once we have launched a service in step 2). + +### 2 — Launch a Service — Træfik Detects It and Creates a Route for You + +Now that we have a Træfik instance up and running, we will deploy new services. + +Edit your `docker-compose.yml` file and add the following at the end of your file. + +```yaml +# ... + whoami: + image: emilevauge/whoami #A container that exposes an API to show it's IP address + labels: + - "traefik.frontend.rule=Host:whoami.docker.localhost" +``` + +The above defines `whoami`: a simple web service that outputs information about the machine it is deployed on (its IP address, host, and so on). + +Start the `whoami` service with the following command: + +```shell +docker-compose up -d whoami +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik has automatically detected the new container and updated its own configuration. + +When Traefik detects new services, it creates the corresponding routes so you can call them ... _let's see!_ (Here, we're using curl) + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +_Shows the following output:_ +```yaml +Hostname: 8656c8ddca6c +IP: 172.27.0.3 +#... +``` + +### 3 — Launch More Instances — Traefik Load Balances Them + +Run more instances of your `whoami` service with the following command: + +```shell +docker-compose up -d --scale whoami=2 +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik has automatically detected the new instance of the container. + +Finally, see that Træfik load-balances between the two instances of your services by running twice the following command: + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +The output will show alternatively one of the followings: + +```yaml +Hostname: 8656c8ddca6c +IP: 172.27.0.3 +#... +``` + +```yaml +Hostname: 8458f154e1f1 +IP: 172.27.0.4 +# ... +``` + +### 4 — Enjoy Træfik's Magic + +Now that you have a basic understanding of how Træfik can automatically create the routes to your services and load balance them, it might be time to dive into [the documentation](https://docs.traefik.io/) and let Træfik work for you! Whatever your infrastructure is, there is probably [an available Træfik backend](https://docs.traefik.io/configuration/backends/available) that will do the job. + +Our recommendation would be to see for yourself how simple it is to enable HTTPS with [Træfik's let's encrypt integration](https://docs.traefik.io/user-guide/examples/#lets-encrypt-support) using the dedicated [user guide](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/). + +## Resources Here is a talk given by [Emile Vauge](https://github.com/emilevauge) at [GopherCon 2017](https://gophercon.com). You will learn Træfik basics in less than 10 minutes. @@ -80,9 +180,9 @@ You will learn fundamental Træfik features and see some demos with Kubernetes. [![Traefik ContainerCamp UK](https://img.youtube.com/vi/aFtpIShV60I/0.jpg)](https://www.youtube.com/watch?v=aFtpIShV60I) -## Get it +## Downloads -### Binary +### The Official Binary File You can grab the latest binary from the [releases](https://github.com/containous/traefik/releases) page and just run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/master/traefik.sample.toml): @@ -90,113 +190,10 @@ You can grab the latest binary from the [releases](https://github.com/containous ./traefik -c traefik.toml ``` -### Docker +### The Official Docker Image Using the tiny Docker image: ```shell docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik -``` - -## Test it - -You can test Træfik easily using [Docker compose](https://docs.docker.com/compose), with this `docker-compose.yml` file in a folder named `traefik`: - -```yaml -version: '3' - -services: - proxy: - image: traefik - command: --api --docker --docker.domain=docker.localhost --logLevel=DEBUG - networks: - - webgateway - ports: - - "80:80" - - "8080:8080" - volumes: - - /var/run/docker.sock:/var/run/docker.sock - - /dev/null:/traefik.toml - -networks: - webgateway: - driver: bridge -``` - -Start it from within the `traefik` folder: - -```shell -docker-compose up -d -``` - -In a browser, you may open [http://localhost:8080](http://localhost:8080) to access Træfik's dashboard and observe the following magic. - -Now, create a folder named `test` and create a `docker-compose.yml` in it with this content: - -```yaml -version: '3' - -services: - whoami: - image: emilevauge/whoami - networks: - - web - labels: - - "traefik.backend=whoami" - - "traefik.frontend.rule=Host:whoami.docker.localhost" - -networks: - web: - external: - name: traefik_webgateway -``` - -Then, start and scale it in the `test` folder: - -```shell -docker-compose up --scale whoami=2 -d -``` - -Finally, test load-balancing between the two services `test_whoami_1` and `test_whoami_2`: - -```shell -curl -H Host:whoami.docker.localhost http://127.0.0.1 -``` - -```yaml -Hostname: ef194d07634a -IP: 127.0.0.1 -IP: ::1 -IP: 172.17.0.4 -IP: fe80::42:acff:fe11:4 -GET / HTTP/1.1 -Host: 172.17.0.4:80 -User-Agent: curl/7.35.0 -Accept: */* -Accept-Encoding: gzip -X-Forwarded-For: 172.17.0.1 -X-Forwarded-Host: 172.17.0.4:80 -X-Forwarded-Proto: http -X-Forwarded-Server: dbb60406010d -``` - -```shell -curl -H Host:whoami.docker.localhost http://127.0.0.1 -``` - -```yaml -Hostname: 6c3c5df0c79a -IP: 127.0.0.1 -IP: ::1 -IP: 172.17.0.3 -IP: fe80::42:acff:fe11:3 -GET / HTTP/1.1 -Host: 172.17.0.3:80 -User-Agent: curl/7.35.0 -Accept: */* -Accept-Encoding: gzip -X-Forwarded-For: 172.17.0.1 -X-Forwarded-Host: 172.17.0.3:80 -X-Forwarded-Proto: http -X-Forwarded-Server: dbb60406010d -``` +``` \ No newline at end of file diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md new file mode 100644 index 000000000..7deb4faf6 --- /dev/null +++ b/examples/quickstart/README.md @@ -0,0 +1,106 @@ +## The Træfik Quickstart (Using Docker) + +In this quickstart, we'll use [Docker compose](https://docs.docker.com/compose) to create our demo infrastructure. + +To save some time, you can clone [Træfik's repository](https://github.com/containous/traefik) and use the quickstart files located in the [examples/quickstart](https://github.com/containous/traefik/tree/master/examples/quickstart/) directory. + +### 1 — Launch Træfik — Tell It to Listen to Docker + +Create a `docker-compose.yml` file where you will define a `reverse-proxy` service that uses the official Træfik image: + +```yaml +version: '3' + +services: + reverse-proxy: + image: traefik #The official Traefik docker image + command: --api --docker #Enables the web UI and tells Træfik to listen to docker + ports: + - "80:80" #The HTTP port + - "8080:8080" #The Web UI (enabled by --api) + volumes: + - /var/run/docker.sock:/var/run/docker.sock #So that Traefik can listen to the Docker events +``` + +**That's it. Now you can launch Træfik!** + +Start your `reverse-proxy` with the following command: + +```shell +docker-compose up -d reverse-proxy +``` + +You can open a browser and go to [http://localhost:8080](http://localhost:8080) to see Træfik's dashboard (we'll go back there once we have launched a service in step 2). + +### 2 — Launch a Service — Træfik Detects It and Creates a Route for You + +Now that we have a Træfik instance up and running, we will deploy new services. + +Edit your `docker-compose.yml` file and add the following at the end of your file. + +```yaml +# ... + whoami: + image: emilevauge/whoami #A container that exposes an API to show it's IP address + labels: + - "traefik.frontend.rule=Host:whoami.docker.localhost" +``` + +The above defines `whoami`: a simple web service that outputs information about the machine it is deployed on (its IP address, host, and so on). + +Start the `whoami` service with the following command: + +```shell +docker-compose up -d whoami +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik has automatically detected the new container and updated its own configuration. + +When Traefik detects new services, it creates the corresponding routes so you can call them ... _let's see!_ (Here, we're using curl) + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +_Shows the following output:_ +```yaml +Hostname: 8656c8ddca6c +IP: 172.27.0.3 +#... +``` + +### 3 — Launch More Instances — Traefik Load Balances Them + +Run more instances of your `whoami` service with the following command: + +```shell +docker-compose up -d --scale whoami=2 +``` + +Go back to your browser ([http://localhost:8080](http://localhost:8080)) and see that Træfik has automatically detected the new instance of the container. + +Finally, see that Træfik load-balances between the two instances of your services by running twice the following command: + +```shell +curl -H Host:whoami.docker.localhost http://127.0.0.1 +``` + +The output will show alternatively one of the followings: + +```yaml +Hostname: 8656c8ddca6c +IP: 172.27.0.3 +#... +``` + +```yaml +Hostname: 8458f154e1f1 +IP: 172.27.0.4 +# ... +``` + +### 4 — Enjoy Træfik's Magic + +Now that you have a basic understanding of how Træfik can automatically create the routes to your services and load balance them, it might be time to dive into [the documentation](https://docs.traefik.io/) and let Træfik work for you! Whatever your infrastructure is, there is probably [an available Træfik backend](https://docs.traefik.io/configuration/backends/available) that will do the job. + +Our recommendation would be to see for yourself how simple it is to enable HTTPS with [Træfik's let's encrypt integration](https://docs.traefik.io/user-guide/examples/#lets-encrypt-support) using the dedicated [user guide](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/). \ No newline at end of file diff --git a/examples/quickstart/docker-compose.yml b/examples/quickstart/docker-compose.yml new file mode 100644 index 000000000..f31f5d408 --- /dev/null +++ b/examples/quickstart/docker-compose.yml @@ -0,0 +1,18 @@ +version: '3' + +services: + #The reverse proxy service (Træfik) + reverse-proxy: + image: traefik #The official Traefik docker image + command: --api --docker #Enables the web UI and tells Træfik to listen to docker + ports: + - "80:80" #The HTTP port + - "8080:8080" #The Web UI (enabled by --api) + volumes: + - /var/run/docker.sock:/var/run/docker.sock #So that Traefik can listen to the Docker events + + #A container that exposes a simple API + whoami: + image: emilevauge/whoami #A container that exposes an API to show it's IP address + labels: + - "traefik.frontend.rule=Host:whoami.docker.localhost" \ No newline at end of file