refactor: typo and move some blocks

README.md

@@ -9,62 +9,7 @@
 - **Handles SSL:** Sozu handles SSL, so your backend servers can focus on what they do best.
 - **Protects your network:** Sozu protect backends by shielding them behind the reverse proxy, limiting direct network access. Sozu uses Rust, a language primed for memory safety. And even if a worker is exploited, sozu workers are sandboxed.
 
-## Building and starting
-
-Requirements:
-- openssl 1.0.1 or above (including libraries/includes, ie apt install libssl-dev / rpm install openssl-devel
-
-You can create the required executables like this:
-
-```
-cd ctl && cargo build; cd ../bin && cargo build
-```
-
-This will create the `sozu` executable for the reverse proxy, and `sozuctl` to command it.
-
-To start the reverse proxy:
-
-```
-cd bin;
-../target/debug/sozu start -c config.toml
-```
-
-You can edit the reverse proxy's configuration with the `config.toml` file. You can declare
-new applications, their frontends and backends through that file, but for more flexibility,
-you should use the command socket (you can find one end of that unix socket at the path
-designed by `command_socket` in the configuration file).
-
-`sozuctl` has a few commands you can use to interact with the reverse proxy:
-
-
-- soft shutdown (wait for active connections to stop): `sozuctl -c config.toml shutdown`
-- hard shutdown: `sozuctl -c config.toml shutdown --hard`
-- display the list of current configuration messages: `sozuctl -c config.toml state dump`
-- save the configuration state to a file: `sozuctl -c config.toml state save -f state.json`
-
-### For OSX build
-
-Mac OS uses an old version of openssl, so we need to use one from Homebrew:
-
-```
-brew install openssl
-brew link --force openssl
-```
-
-If it does not work, set the following environment variables before building:
-
-```
-export OPENSSL_LIB_DIR=/usr/local/opt/openssl/lib/
-export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
-```
-
-## Logging
-
-The reverse proxy uses `env_logger`. You can select which module displays logs at which level with an environment variable. Here is an example to display most logs at `info` level, but use `trace` level for the HTTP parser module:
-
-```
-RUST_LOG=info,sozu_lib::parser::http11=trace ./target/debug/sozu
-```
+To get started check out our [documentation](./doc/README.md) !
 
 ## Exploring the source
 

doc/architecture.md

@@ -20,7 +20,6 @@ The configuration messages are transmitted in JSON format, and they are defined
 
 The master exposes a unix socket for configuration instead of a HTTP server on localhost because unix socket access can be secured through file system permissions.
 
-
 ## Proxying
 
 ### Event loop with mio
@@ -51,7 +50,7 @@ The [logger](https://github.com/sozu-proxy/sozu/blob/3111e2db420d2773b1f0404d655
 
 The logger can be invoked through a thread local storage variable accessible from anywhere with logging macros.
 
-# Metrics
+## Metrics
 
 [Metrics](https://github.com/sozu-proxy/sozu/tree/3111e2db420d2773b1f0404d6556f40b2f2ea85b/lib/src/network/metrics) work like the logger, accessible from anywhere with macros and TLS. We support two "drains": one that sends the metrics on the networks with a statsd compatible protocol, and one aggregating metrics locally, to be queried through the configuration socket.
 

doc/debugging_strategies.md

@@ -9,7 +9,7 @@ Sozu provides logs and metrics allowing detection of most production issues.
 It is useful to gather information on the configuration state in a production system.
 Here are some commands you can use to take a snapshot of the current state:
 
-```
+```bash
 sozuctl -c /etc/config.toml status > "sozu-status-$(date -Iseconds).txt"
 sozuctl -c /etc/config.toml metrics > "sozu-metrics-$(date -Iseconds).txt"
 sozuctl -c /etc/config.toml query applications > "sozu-applications-$(date -Iseconds).txt"
@@ -63,11 +63,12 @@ tagged_metrics = true
 
 Access logs have the following format:
 
-```
+```txt
 2018-09-21T14:01:51Z 821136800672570 71013 WRK-00 INFO  450b071a-53b8-4fd7-b2f2-1213f03ef032 MyApp      127.0.0.1:52323 -> 127.0.0.1:1027       241ms 855μs 560 33084   200 OK lolcatho.st:8080 GET /
 ```
 
 From left to right:
+
 * date in ISO8601 format, UTC timezone
 * monotonic clock (in case some messages appear in the wrong order)
 * PID
@@ -146,19 +147,19 @@ after the circuit breaker triggered (we wait for 3 failed connections to the bac
 
 A backend connection error would result in the following log message:
 
-```
+```txt
 2018-09-21T14:36:08Z 823194694977734 71501 WRK-00 ERROR 839f592b-a194-4c3b-848b-8ef024129969    MyApp    error connecting to backend, trying again
 ```
 
 The circuit breaker triggering will write this to the logs:
 
-```
+```txt
 2018-09-21T14:36:57Z 823243245414405 71524 WRK-00 ERROR 7029d66e-57a8-406e-ae61-e4bf9ff7b6b8    MyApp    max connection attempt reached
 ```
 
 The retry policy marking a backend server as down will write the following log message:
 
-```
+```txt
 2018-09-21T14:37:31Z 823277868708804 71524 WRK-00 ERROR no more available backends for app MyApp
 ```
 
@@ -215,7 +216,6 @@ OpenSSL specific:
 * `sozu.openssl.wrong_version_number.error`: invalid TLS version
 * `sozu.openssl.unknown_protocol.error`: most likely, someone tried plaintext HTTP instead of HTTPS
 
-
 Rustls specific, negotiated ciphersuite:
 
 * `sozu.tls.cipher.TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`
@@ -237,13 +237,13 @@ Normal traffic (`sozu.http.requests`) drops while 404 (`sozu.http.404.errors`) a
 503 (`sozu.http.503.errors`), that means sozu's configuration is probably invalid.
 Check the configuration state with;
 
-```
+```bash
 sozuctl -c /etc/config.toml query applications
 ```
 
 And, for the complete configuration for a specific application id:
 
-```
+```bash
 sozuctl -c /etc/config.toml query applications -i app_id
 ```
 

doc/design_motivation.md

@@ -70,6 +70,7 @@ Sōzu should have a very predictable behaviour in its memory usage and its laten
 Any irregularity should be observed and removed.
 
 It drove various decisions:
+
 - Rust allowed us to avoid garbage collection pauses
 - preallocations and pooling to avoid some allocations in the hot path
 - single threaded, shared nothing architecture to avoid synchronization between cores

doc/getting_started.md

@@ -11,8 +11,8 @@ After you did that, `Rust` should be fully installed.
 
 ### Required dependencies
 
-* openssl 1.0.1 or above
-* libssl-dev
+- openssl 1.0.1 or above
+- libssl-dev
 
 ### Install
 
@@ -24,16 +24,34 @@ They will be built and available in the `~/.cargo/bin` folder.
 
 ### Build from source
 
-* Build the sozu executable
+Build the sozu executable:
 
 `cd bin && cargo build --release`
 
 > The `--release` parameter inform cargo to compile sozu with optimizations turned on.
 > Only use `--release` to make a production version.
 
-* Build the sozuctl executable to manage the reverse proxy
+Build the sozuctl executable to manage the reverse proxy:
 
 `cd ctl && cargo build --release;`
 
+This will create the `sozu` executable for the reverse proxy, and `sozuctl` to command it.
+
 [ru]: https://rustup.rs
 [cr]: https://crates.io/
+
+#### For OSX build
+
+Mac OS uses an old version of openssl, so we need to use one from Homebrew:
+
+```bash
+brew install openssl
+brew link --force openssl
+```
+
+If it does not work, set the following environment variables before building:
+
+```bash
+export OPENSSL_LIB_DIR=/usr/local/opt/openssl/lib/
+export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
+```

doc/how_to_use.md

@@ -1,6 +1,6 @@
 # How to use Sōzu
 
-> Before a deep dive in the configuration part of the proxy, you should take a look at the [getting started documentation](./getting_started.md) if you haven't done it yet.
+> If you didn't take a look at the [configure documentation](./configure.md), we advise you to do so because you will need to know what to put in your configuration file.
 
 ## Run it
 
@@ -14,7 +14,35 @@ However, if you built the project from source, `sozu` and `sozuctl` are placed i
 
 > `cargo build --release` puts the resulting binary in `target/release` instead of `target/debug`.
 
-You can find a working `config.toml` exemple [here][cfg]. For a proper install, you can move it to your `/etc/sozu/config.toml`.
+You can find a working `config.toml` exemple [here][cfg].
+
+To start the reverse proxy:
+
+```bash
+sozu start -c config.toml
+```
+
+You can edit the reverse proxy's configuration with the `config.toml` file. You can declare
+new applications, their frontends and backends through that file, but for more flexibility,
+you should use the command socket (you can find one end of that unix socket at the path
+designed by `command_socket` in the configuration file).
+
+`sozuctl` has a few commands you can use to interact with the reverse proxy:
+
+- soft shutdown (wait for active connections to stop): `sozuctl -c config.toml shutdown`
+- hard shutdown: `sozuctl -c config.toml shutdown --hard`
+- display the list of current configuration messages: `sozuctl -c config.toml state dump`
+- save the configuration state to a file: `sozuctl -c config.toml state save -f state.json`
+
+Checkout sozuctl [documentation](../ctl/README.md) for more informations.
+
+## Logging
+
+The reverse proxy uses `env_logger`. You can select which module displays logs at which level with an environment variable. Here is an example to display most logs at `info` level, but use `trace` level for the HTTP parser module:
+
+```bash
+RUST_LOG=info,sozu_lib::parser::http11=trace ./target/debug/sozu
+```
 
 ## Run it with Docker
 
@@ -62,8 +90,8 @@ Sozu can use a JSON file to load an initial configuration state for its routing.
 
 To change the path of the saved state file, modify the `saved_state` option in the configuration file (default value is `/var/lib/sozu/state.json`).
 
-[cfg]: https://github.com/sozu-proxy/sozu/blob/master/bin/config.toml
-[df]: https://github.com/sozu-proxy/sozu/blob/master/Dockerfile
+[cfg]: ../bin/config.toml
+[df]: ../Dockerfile
 
 ## Systemd integration
 
@@ -75,8 +103,18 @@ This will make systemd take notice of it, and now you can start the service with
 
 Furthermore, we can enable it, so that it is activated by default on future boots with `systemctl enable sozu.service`.
 
-> You can use a `bash` script and call `sed` to automte this part. e.g.: [generate.sh][gen]
-> You have to set your own `__BINDIR__` and `__SYSCONFDIR__`.
+You can use a `bash` script and call `sed` to automate this part. e.g.: [generate.sh][gen].
+
+This script will generate `sozu.service`, `sozu.conf` and `config.toml` files into a `generated` folder at the root `os-build` directory.
+
+You willd have to set your own `__BINDIR__`, `__SYSCONFDIR__`, `__DATADIR__` and `__RUNDIR__` variables.
+
+Here is an example of those variables:
+
+- `__BINDIR__` : `/usr/local/bin`
+- `__SYSCONFDIR__` : `/etc`
+- `__DATADIR__` : `/var/lib/sozu`
+- `__RUNDIR__` : `/run`
 
-[un]: https://github.com/sozu-proxy/sozu/blob/master/os-build/systemd/sozu.service.in
-[gen]: https://github.com/sozu-proxy/sozu/blob/master/os-build/exherbo/generate.sh
+[un]: ../os-build/systemd/sozu.service.in
+[gen]: ../os-build/exherbo/generate.sh

doc/tools_libraries.md

@@ -1,5 +1,5 @@
 # Tools & Libraries
 
-## Client in other languages
+## Client in other languages
 
-* Elixir - [exsozu](https://github.com/evuez/exsozu)
+- Elixir - [exsozu](https://github.com/evuez/exsozu)