From 7d3878214adfc5ec4d55e131aeb2d3853b38e6e9 Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Thu, 10 Aug 2017 17:29:32 +0200 Subject: [PATCH] Update documentation --- .github/CONTRIBUTING.md | 69 +++++++++++++++++++++++++++++++++----- .github/MAINTAINER.md | 33 +++++++++++++----- README.md | 74 ++++++++++++++++++++++++++--------------- 3 files changed, 133 insertions(+), 43 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 1504163ba..f2d4ad105 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,10 +1,10 @@ # Contributing -### Building +## Building You need either [Docker](https://github.com/docker/docker) and `make` (Method 1), or `go` (Method 2) in order to build traefik. For changes to its dependencies, the `glide` dependency management tool and `glide-vc` plugin are required. -#### Method 1: Using `Docker` and `Makefile` +### Method 1: Using `Docker` and `Makefile` You need to run the `binary` target. This will create binaries for Linux platform in the `dist` folder. @@ -26,9 +26,9 @@ $ ls dist/ traefik* ``` -#### Method 2: Using `go` +### Method 2: Using `go` -###### Setting up your `go` environment +##### Setting up your `go` environment - You need `go` v1.8+ - It is recommended you clone Træfik into a directory like `~/go/src/github.com/containous/traefik` (This is the official golang workspace hierarchy, and will allow dependencies to resolve properly) @@ -55,7 +55,7 @@ GORACE="" ## more go env's will be listed ``` -###### Build Træfik +##### Build Træfik Once your environment is set up and the Træfik repository cloned you can build Træfik. You need get `go-bindata` once to be able to use `go generate` command as part of the build. The steps to build are: @@ -75,7 +75,7 @@ go build ./cmd/traefik You will find the Træfik executable in the `~/go/src/github.com/containous/traefik` folder as `traefik`. -#### Setting up `glide` and `glide-vc` for dependency management +### Setting up `glide` and `glide-vc` for dependency management - Glide is not required for building; however, it is necessary to modify dependencies (i.e., add, update, or remove third-party packages) - Glide can be installed either via homebrew: `$ brew install glide` or via the official glide script: `$ curl https://glide.sh/get | sh` @@ -99,7 +99,7 @@ $ go build ./cmd/traefik ### Tests -##### Method 1: `Docker` and `make` +#### Method 1: `Docker` and `make` You can run unit tests using the `test-unit` target and the integration test using the `test-integration` target. @@ -136,14 +136,14 @@ TESTFLAGS="-check.f MyTestSuite.*Test" make test-integration More: https://labix.org/gocheck -##### Method 2: `go` +#### Method 2: `go` - Tests can be run from the cloned directory, by `$ go test ./...` which should return `ok` similar to: ``` ok _/home/vincent/src/github/vdemeester/traefik 0.004s ``` -### Documentation +## Documentation The [documentation site](http://docs.traefik.io/) is built with [mkdocs](http://mkdocs.org/) @@ -173,3 +173,54 @@ INFO - Cleaning site directory [I 160505 22:31:24 handlers:59] Start watching changes [I 160505 22:31:24 handlers:61] Start detecting changes ``` + + +## How to Write a Good Issue + +Please keep in mind that the GitHub issue tracker is not intended as a general support forum, but for reporting bugs and feature requests. + +For end-user related support questions, refer to one of the following: +- the Traefik 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) +- [Stack Overflow](https://stackoverflow.com/questions/tagged/traefik) (using the `traefik` tag) + +### Title + +The title must be short and descriptive. (~60 characters) + +### Description + +- Respect the issue template as more as possible. [template](ISSUE_TEMPLATE.md) +- If it's possible use the command `traefik bug`. See https://www.youtube.com/watch?v=Lyz62L8m93I. +- Explain the conditions which led you to write this issue: the context. +- The context should lead to something, an idea or a problem that you’re facing. +- Remain clear and concise. +- Format your messages to help the reader focus on what matters and understand the structure of your message, use [Markdown syntax](https://help.github.com/articles/github-flavored-markdown) + + +## How to Write a Good Pull Request + +### Title + +The title must be short and descriptive. (~60 characters) + +### Description + +- Respect the pull request template as more as possible. [template](PULL_REQUEST_TEMPLATE.md) +- Explain the conditions which led you to write this PR: the context. +- The context should lead to something, an idea or a problem that you’re facing. +- Remain clear and concise. +- Format your messages to help the reader focus on what matters and understand the structure of your message, use [Markdown syntax](https://help.github.com/articles/github-flavored-markdown) + +### Content + +- Make it small. +- Do only one thing. +- Write useful descriptions and titles. +- Avoid re-formatting. +- Make sure the code builds. +- Make sure all tests pass. +- Add tests. +- Address review comments in terms of additional commits. +- Do not amend/squash existing ones unless the PR is trivial. + +Read [10 tips for better pull requests](http://blog.ploeh.dk/2015/01/15/10-tips-for-better-pull-requests/). diff --git a/.github/MAINTAINER.md b/.github/MAINTAINER.md index f3f396dfb..49b3fa040 100644 --- a/.github/MAINTAINER.md +++ b/.github/MAINTAINER.md @@ -1,5 +1,17 @@ # Maintainers +## The team + +- Emile Vauge [@emilevauge](https://github.com/emilevauge) +- Vincent Demeester [@vdemeester](https://github.com/vdemeester) +- Ed Robinson [@errm](https://github.com/errm) +- Daniel Tomcej [@dtomcej](https://github.com/dtomcej) +- Manuel Zapf [@SantoDE](https://github.com/SantoDE) +- Timo Reimann [@timoreimann](https://github.com/timoreimann) +- Ludovic Fernandez [@ldez](https://github.com/ldez) +- Julien Salleyron [@juliens](https://github.com/juliens) +- Nicolas Mengin [@nmengin](https://github.com/nmengin) + ## Labels If we open/look an issue/PR, we must add a `kind/*` and an `area/*`. @@ -7,6 +19,7 @@ If we open/look an issue/PR, we must add a `kind/*` and an `area/*`. ### Contributor * `contributor/need-more-information`: we need more information from the contributor in order to analyze a problem. +* `contributor/waiting-for-feedback`: we need the contributor to give us feedback. * `contributor/waiting-for-corrections`: we need the contributor to take actions in order to move forward with a PR. **(only for PR)** * `contributor/needs-resolve-conflicts`: use it only when there is some conflicts (and an automatic rebase is not possible). **(only for PR)** _[bot, humans]_ @@ -34,6 +47,17 @@ If we open/look an issue/PR, we must add a `kind/*` and an `area/*`. ### Area +* `area/acme`: ACME related. +* `area/api`: Traefik API related. +* `area/authentication`: Authentication related. +* `area/cluster`: Traefik clustering related. +* `area/documentation`: regards improving/adding documentation. +* `area/infrastructure`: related to CI or Traefik building scripts. +* `area/healthcheck`: Health-check related. +* `area/logs`: Traefik logs related. +* `area/middleware`: Middleware related. +* `area/middleware/metrics`: Metrics related. (Prometheus, StatsD, ...) +* `area/oxy`: Oxy related. * `area/provider`: related to all providers. * `area/provider/boltdb`: Boltd DB related. * `area/provider/consul`: Consul related. @@ -46,17 +70,10 @@ If we open/look an issue/PR, we must add a `kind/*` and an `area/*`. * `area/provider/mesos`: Mesos related. * `area/provider/rancher`: Rancher related. * `area/provider/zk`: Zoo Keeper related. -* `area/middleware`: Middleware related. -* `area/acme`: ACME related. -* `area/authentication`: Authentication related. -* `area/api`: Traefik API related. -* `area/logs`: Traefik logs related. * `area/sticky-session`: Sticky session related. +* `area/tls`: TLS related. * `area/websocket`: WebSocket related. * `area/webui`: Web UI related. -* `area/infrastructure`: related to CI or Traefik building scripts. -* `area/documentation`: regards improving/adding documentation. -* `area/cluster`: Traefik clustering related. ### Priority diff --git a/README.md b/README.md index 95bb494c7..70f7446cc 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,24 @@ Træfik (pronounced like [traffic](https://speak-ipa.bearbin.net/speak.cgi?speak=%CB%88tr%C3%A6f%C9%AAk)) 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](https://docs.docker.com/swarm), [Kubernetes](http://kubernetes.io), [Marathon](https://mesosphere.github.io/marathon/), [Mesos](https://github.com/apache/mesos), [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 DynamoDB](https://aws.amazon.com/dynamodb/), Rest API, file...) to manage its configuration automatically and dynamically. +--- + +| **[Overview](#overview)** | +**[Features](#features)** | +**[Quickstart](#quickstart)** | +**[Web UI](#web-ui)** | +**[Test it](#test-it)** | +**[Documentation](#documentation)** | +**[Support](#support)** | +**[Release cycle](#release-cycle)** | + +| **[Contributing](#contributing)** | +**[Maintainers](#maintainers)** | +**[Plumbing](#plumbing)** | +**[Credits](#credits)** | + +--- + ## 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. @@ -36,8 +54,6 @@ Træfik can listen to your service registry/orchestrator API, and knows each tim Routes to your services will be created instantly. Run it and forget it! - - ## Features @@ -62,6 +78,7 @@ Run it and forget it! - [Let's Encrypt](https://letsencrypt.org) support (Automatic HTTPS with renewal) - High Availability with cluster mode + ## 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. @@ -76,6 +93,7 @@ You will learn fundamental Træfik features and see some demos with Docker, Meso [![Traefik Devoxx France](http://img.youtube.com/vi/QvAz9mVx5TI/0.jpg)](http://www.youtube.com/watch?v=QvAz9mVx5TI) + ## Web UI You can access the simple HTML frontend of Træfik. @@ -83,12 +101,6 @@ 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) -## Plumbing - -- [Oxy](https://github.com/vulcand/oxy): an awesome proxy library made by Mailgun folks -- [Gorilla mux](https://github.com/gorilla/mux): famous request router -- [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 ## Test it @@ -98,7 +110,7 @@ You can access the simple HTML frontend of Træfik. ./traefik --configFile=traefik.toml ``` -- Use the tiny Docker image: +- 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 @@ -110,23 +122,21 @@ docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/etc/traefik/traefik.to git clone https://github.com/containous/traefik ``` + ## Documentation You can find the complete documentation [here](https://docs.traefik.io). -## Contributing - -Please refer to [this section](.github/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. ## Support -You can join [![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) to get basic support. +To get basic support, you can: +- join the Traefik 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 @@ -142,17 +152,29 @@ If you prefer commercial support, please contact [containo.us](https://containo. - We use [Semantic Versioning](http://semver.org/) +## Contributing + +Please refer to [contributing documentation](.github/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 -- Emile Vauge [@emilevauge](https://github.com/emilevauge) -- Vincent Demeester [@vdemeester](https://github.com/vdemeester) -- Ed Robinson [@errm](https://github.com/errm) -- Daniel Tomcej [@dtomcej](https://github.com/dtomcej) -- Manuel Zapf [@SantoDE](https://github.com/SantoDE) -- Timo Reimann [@timoreimann](https://github.com/timoreimann) -- Ludovic Fernandez [@ldez](https://github.com/ldez) -- Julien Salleyron [@juliens](https://github.com/juliens) -- Nicolas Mengin [@nmengin](https://github.com/nmengin) +[Information about process and maintainers](.github/MAINTAINER.md) + + +## Plumbing + +- [Oxy](https://github.com/vulcand/oxy): an awesome proxy library made by Mailgun folks +- [Gorilla mux](https://github.com/gorilla/mux): famous request router +- [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