Add some more docs

Signed-off-by: Gabriel Adrian Samfira <[email protected]>

README.md

@@ -116,20 +116,20 @@ Follow the instructions in the README of each provider to install them.
 The ```garm``` configuration is a simple ```toml```. The sample config file in [the testdata folder](/testdata/config.toml) is fairly well commented and should be enough to get you started. The configuration file is split into several sections, each of which is documented in its own page. The sections are:
 
 * [The default section](/doc/config_default.md)
+* [Database](/doc/database.md)
+* [Github credentials](/doc/github_credentials.md)
+* [Providers](/doc/providers.md)
 * [Metrics](/doc/config_metrics.md)
 * [JWT authentication](/doc/config_jwt_auth.md)
 * [API server](/doc/config_api_server.md)
-* [Github credentials](/doc/github_credentials.md)
-* [Providers](/doc/providers.md)
-* [Database](/doc/database.md)
 
 Once you've configured your database, providers and github credentials, you'll need to configure your [webhooks and the callback_url](/doc/webhooks_and_callbacks.md).
 
 At this point, you should be done. Have a look at the [running garm document](/doc/running_garm.md) for usage instructions and available features.
 
 If you would like to use ```garm``` with a different IaaS than the ones already available, have a look at the [writing an external provider](/doc/external_provider.md) page.
 
-If you like to optimize the startup time of new instance, take a look at the [performance considerations](/doc/performance_considerations.md) page.
+If you would like to optimize the startup time of new instance, take a look at the [performance considerations](/doc/performance_considerations.md) page.
 
 ## Write your own provider
 

doc/config_api_server.md

@@ -29,4 +29,6 @@ The config options are fairly straight forward.
     key = ""
 ```
 
-The GARM API server has the option to enable TLS, but I suggest you use a reverse proxy and enable TLS termination in that reverse proxy. There is an `nginx` sample in this repository.
+The GARM API server has the option to enable TLS, but I suggest you use a reverse proxy and enable TLS termination in that reverse proxy. There is an `nginx` sample in this repository with TLS termination enabled.
+
+You can of course enable TLS in both garm and the reverse proxy. The choice is yours.

doc/config_jwt_auth.md

@@ -6,8 +6,7 @@ It is recommended that the secret be a long, randomly generated string. Changing
 
 ```toml
 [jwt_auth]
-# A JWT token secret used to sign tokens.
-# Obviously, this needs to be changed :).
+# A JWT token secret used to sign tokens. Obviously, this needs to be changed :).
 secret = ")9gk_4A6KrXz9D2u`0@MPea*sd6W`%@5MAWpWWJ3P3EqW~qB!!(Vd$FhNc*eU4vG"
 
 # Time to live for tokens. Both the instances and you will use JWT tokens to

doc/config_metrics.md

@@ -0,0 +1,55 @@
+# The metrics section
+
+This is one of the features in GARM that I really love having. For one thing, it's community contributed and for another, it really adds value to the project. It allows us to create some pretty nice visualizations of what is happening with GARM.
+
+At the moment there are only three meaningful metrics being collected, besides the default ones that the prometheus golang package enables by default. These are:
+
+* `garm_health` - This is a gauge that is set to 1 if GARM is healthy and 0 if it is not. This is useful for alerting.
+* `garm_runner_status` - This is a gauge value that gives us details about the runners garm spawns
+* `garm_webhooks_received` - This is a counter that increments every time GARM receives a webhook from GitHub.
+
+More metrics will be added in the future.
+
+## Enabling metrics
+
+Metrics are disabled by default. To enable them, add the following to your config file:
+
+```toml
+[metrics]
+# Toggle metrics. If set to false, the API endpoint for metrics collection will
+# be disabled.
+enable = true
+# Toggle to disable authentication (not recommended) on the metrics endpoint.
+# If you do disable authentication, I encourage you to put a reverse proxy in front
+# of garm and limit which systems can access that particular endpoint. Ideally, you
+# would enable some kind of authentication using the reverse proxy, if the built-in auth
+# is not sufficient for your needs.
+disable_auth = false
+```
+
+You can choose to disable authentication if you wish, however it's not terribly difficult to set up, so I generally advise against disabling it.
+
+## Configuring prometheus
+
+The following section assumes that your garm instance is running at `garm.example.com` and has TLS enabled.
+
+First, generate a new JWT token valid only for the metrics endpoint:
+
+```bash
+garm-cli metrics-token create
+```
+
+Note: The token validity is equal to the TTL you set in the [JWT config section](/doc/config_jwt_auth.md).
+
+Copy the resulting token, and add it to your prometheus config file. The following is an example of how to add garm as a target in your prometheus config file:
+
+```yaml
+scrape_configs:
+  - job_name: "garm"
+    # Connect over https. If you don't have TLS enabled, change this to http.
+    scheme: https
+    static_configs:
+      - targets: ["garm.example.com"]
+    authorization:
+      credentials: "superSecretTokenYouGeneratedEarlier"
+```