traefik/README.md

157 lines
5.7 KiB
Markdown
Raw Normal View History

2015-09-14 22:03:53 +00:00
![Træfɪk](http://traefik.github.io/traefik.logo.svg "Træfɪk")
2015-09-22 08:33:37 +00:00
___
2015-09-13 17:34:05 +00:00
2015-10-28 10:39:24 +00:00
[![Circle CI](https://circleci.com/gh/emilevauge/traefik.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/emilevauge/traefik)
2015-09-14 22:03:53 +00:00
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/EmileVauge/traefik/blob/master/LICENSE.md)
2015-10-28 10:39:24 +00:00
[![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)
2015-09-22 14:07:49 +00:00
2015-09-14 09:41:50 +00:00
2015-09-14 09:14:37 +00:00
Træfɪk is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease.
2015-10-03 14:51:14 +00:00
It supports several backends ([Docker :whale:](https://www.docker.com/), [Mesos/Marathon](https://mesosphere.github.io/marathon/), [Consul](https://consul.io/), [Etcd](https://coreos.com/etcd/), [Zookeeper](https://zookeeper.apache.org), [BoltDB](https://github.com/boltdb/bolt), Rest API, file...) to manage its configuration automatically and dynamically.
2015-09-13 17:34:05 +00:00
2015-09-14 09:01:47 +00:00
## Features
- No dependency hell, single binary made with go
- Simple json Rest API
- Simple TOML file configuration
- Multiple backends supported: Docker, Mesos/Marathon, Consul, Etcd, and more to come
- Watchers for backends, can listen change in backends to apply a new configuration automatically
- Hot-reloading of configuration. No need to restart the process
- Graceful shutdown http connections during hot-reloads
- Circuit breakers on backends
- Round Robin, rebalancer load-balancers
- Rest Metrics
- Tiny docker image included
- SSL backends support
- SSL frontend support
2015-10-13 16:05:50 +00:00
- Clean AngularJS Web UI
- Websocket support
## Demo
2015-09-28 16:25:41 +00:00
Here is a demo of Træfɪk using Docker backend, showing a load-balancing between two servers, hot reloading of configuration, and graceful shutdown.
[![asciicast](https://asciinema.org/a/4tcyde7riou5vxulo6my3mtko.png)](https://asciinema.org/a/4tcyde7riou5vxulo6my3mtko)
2015-10-13 16:05:50 +00:00
## Web UI
You can access to a simple HTML frontend of Træfik.
![Web UI Providers](docs/img/web.frontend.png)
![Web UI Health](docs/img/traefik-health.png)
## Plumbing
2015-09-13 17:34:05 +00:00
- [Oxy](https://github.com/mailgun/oxy/): an awsome proxy library made by Mailgun guys
- [Gorilla mux](https://github.com/gorilla/mux): famous request router
- [Negroni](https://github.com/codegangsta/negroni): web middlewares made simple
- [Manners](https://github.com/mailgun/manners): graceful shutdown of http.Handler servers
2015-09-13 17:34:05 +00:00
## Quick start
2015-09-13 17:34:05 +00:00
- The simple way: grab the latest binary from the [releases](https://github.com/emilevauge/traefik/releases) page and just run it with the [sample configuration file](https://raw.githubusercontent.com/EmileVauge/traefik/master/traefik.sample.toml):
2015-09-13 17:34:05 +00:00
```shell
2015-09-14 12:38:21 +00:00
./traefik traefik.toml
2015-09-13 17:34:05 +00:00
```
2015-09-14 12:38:21 +00:00
- Use the tiny Docker image:
2015-09-13 17:34:05 +00:00
```shell
2015-09-14 22:03:53 +00:00
docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/traefik.toml emilevauge/traefik
2015-09-13 17:34:05 +00:00
```
- From sources:
2015-09-22 08:50:33 +00:00
```shell
2015-09-22 08:50:33 +00:00
git clone https://github.com/EmileVauge/traefik
```
## Documentation
2015-09-22 08:33:37 +00:00
You can find the complete documentation [here](docs/index.md).
## Benchmarks
Refer to the [benchmarks section](docs/index.md#benchmarks) in the documentation.
## Contributing
### Building
2015-10-13 20:57:10 +00:00
You need either [Docker](https://github.com/docker/docker) and `make`, or `go` and `glide` in order to build traefik.
2015-10-13 20:57:10 +00:00
#### Setting up your `go` environment
2015-10-13 20:57:10 +00:00
- You need `go` v1.5
- You need to set `export GO15VENDOREXPERIMENT=1` environment variable
- You need `go-bindata` to be able to use `go generate` command (needed to build) : `go get github.com/jteeuwen/go-bindata/...`.
2015-10-13 20:57:10 +00:00
- If you clone Træfɪk into something like `~/go/src/github.com/traefik`, your `GOPATH` variable will have to be set to `~/go`: export `GOPATH=~/go`.
#### Using `Docker` and `Makefile`
You need to run the `binary` target. This will create binaries for Linux platform in the `dist` folder.
```bash
$ make binary
2015-10-13 20:57:10 +00:00
docker build -t "traefik-dev:no-more-godep-ever" -f build.Dockerfile .
Sending build context to Docker daemon 295.3 MB
Step 0 : FROM golang:1.5
---> 8c6473912976
Step 1 : RUN go get github.com/Masterminds/glide
[...]
docker run --rm -v "/var/run/docker.sock:/var/run/docker.sock" -it -e OS_ARCH_ARG -e OS_PLATFORM_ARG -e TESTFLAGS -v "/home/emile/dev/go/src/github.com/emilevauge/traefik/"dist":/go/src/github.com/emilevauge/traefik/"dist"" "traefik-dev:no-more-godep-ever" ./script/make.sh generate binary
---> Making bundle: generate (in .)
removed 'gen.go'
---> Making bundle: binary (in .)
$ ls dist/
2015-10-13 20:57:10 +00:00
traefik*
```
2015-10-13 20:57:10 +00:00
#### Using `glide`
2015-10-13 20:57:10 +00:00
The idea behind `glide` is the following :
2015-10-13 20:57:10 +00:00
- when checkout(ing) a project, **run `glide up`** to install
(`go get …`) the dependencies in the `GOPATH`.
2015-10-13 20:57:10 +00:00
- if you need another dependency, import and use it in
the source, and **run `glide get github.com/Masterminds/cookoo`** to save it in
`vendor` and add it to your `glide.yaml`.
```bash
2015-10-13 20:57:10 +00:00
$ glide up --update-vendored
# generate
$ go generate
# Simple go build
2015-10-13 20:57:10 +00:00
$ go build
# Using gox to build multiple platform
2015-10-13 20:57:10 +00:00
$ gox "linux darwin" "386 amd64 arm" \
-output="dist/traefik_{{.OS}}-{{.Arch}}"
# run other commands like tests
2015-10-13 20:57:10 +00:00
$ go test ./...
ok _/home/vincent/src/github/vdemeester/traefik 0.004s
```
### Tests
You can run unit tests using the `test-unit` target and the
integration test using the `test-integration` target.
```bash
$ make test-unit
docker build -t "traefik-dev:your-feature-branch" -f build.Dockerfile .
# […]
docker run --rm -it -e OS_ARCH_ARG -e OS_PLATFORM_ARG -e TESTFLAGS -v "/home/vincent/src/github/vdemeester/traefik/dist:/go/src/github.com/emilevauge/traefik/dist" "traefik-dev:your-feature-branch" ./script/make.sh generate test-unit
---> Making bundle: generate (in .)
removed 'gen.go'
---> Making bundle: test-unit (in .)
+ go test -cover -coverprofile=cover.out .
ok github.com/emilevauge/traefik 0.005s coverage: 4.1% of statements
Test success
```