Improving docs (#203)

Broke the docs into sections with a left nav.  Improved wording on a few sections as well.

src/docs/config.toml

@@ -15,7 +15,7 @@ publishDir = "../../docs"
 
 [[menu.main]]
     name = "Downloads"
-    url = "/download/"
+    url = "/docs/install/"
 
 [[menu.main]]
     name = "FAQ"

src/docs/content/docs/_index.md

@@ -0,0 +1,8 @@
++++
+show_menu = true
++++
+
+## Welcome to the Cassandra Reaper documentation!
+
+
+

src/docs/content/docs/api.md

@@ -0,0 +1,129 @@
++++
+[menu.docs]
+name = "Rest API"
+weight = 75
++++
+
+# Rest API
+
+
+Source code for all the REST resources can be found from package com.spotify.reaper.resources.
+
+## Ping Resource
+
+* GET     /ping
+  * Expected query parameters: *None*
+  * Simple ping resource that can be used to check whether the reaper is running.
+
+## Cluster Resource
+
+* GET     /cluster
+  * Expected query parameters:
+      * *seedHost*: Limit the returned cluster list based on the given seed host. (Optional)
+  * Returns a list of registered cluster names in the service.
+
+* GET     /cluster/{cluster_name}
+  * Expected query parameters:
+    * *limit*: Limit the number of repair runs returned. Recent runs are prioritized. (Optional)
+  * Returns a cluster object identified by the given "cluster_name" path parameter.
+
+* POST    /cluster
+  * Expected query parameters:
+      * *seedHost*: Host name or IP address of the added Cassandra
+        clusters seed host.
+  * Adds a new cluster to the service, and returns the newly added cluster object,
+    if the operation was successful.
+
+* PUT     /cluster/{cluster_name}
+  * Expected query parameters:
+      * *seedHost*: New host name or IP address used as Cassandra cluster seed.
+  * Modifies a cluster's seed host. Comes in handy when the previous seed has left the cluster.
+
+* DELETE  /cluster/{cluster_name}
+  * Expected query parameters: *None*
+  * Delete a cluster object identified by the given "cluster_name" path parameter.
+    Cluster will get deleted only if there are no schedules or repair runs for the cluster,
+    or the request will fail. Delete repair runs and schedules first before calling this.
+
+## Repair Run Resource
+
+* GET     /repair_run
+  * Optional query parameters:
+    * *state*: Comma separated list of repair run state names. Only names found in
+    com.spotify.reaper.core.RunState are accepted.
+  * Returns a list of repair runs, optionally fetching only the ones with *state* state.
+
+* GET     /repair_run/{id}
+  * Expected query parameters: *None*
+  * Returns a repair run object identified by the given "id" path parameter.
+
+* GET     /repair_run/cluster/{cluster_name} (com.spotify.reaper.resources.RepairRunResource)
+  * Expected query parameters: *None*
+  * Returns a list of all repair run statuses found for the given "cluster_name" path parameter.
+
+* POST    /repair_run
+  * Expected query parameters:
+    * *clusterName*: Name of the Cassandra cluster.
+    * *keyspace*: The name of the table keyspace.
+    * *tables*: The name of the targeted tables (column families) as comma separated list.
+                If no tables given, then the whole keyspace is targeted. (Optional)
+    * *owner*: Owner name for the run. This could be any string identifying the owner.
+    * *cause*: Identifies the process, or cause the repair was started. (Optional)
+    * *segmentCount*: Defines the amount of segments to create for repair run. (Optional)
+    * *repairParallelism*: Defines the used repair parallelism for repair run. (Optional)
+    * *intensity*: Defines the repair intensity for repair run. (Optional)
+    * *incrementalRepair*: Defines if incremental repair should be done. [true/false] (Optional)
+
+* PUT    /repair_run/{id}
+  * Expected query parameters:
+    * *state*: New value for the state of the repair run.
+      Possible values for given state are: "PAUSED" or "RUNNING".
+  * Starts, pauses, or resumes a repair run identified by the "id" path parameter.
+  * Can also be used to reattempt a repair run in state "ERROR", picking up where it left off.
+
+* DELETE  /repair_run/{id}
+  * Expected query parameters:
+    * *owner*: Owner name for the run. If the given owner does not match the stored owner,
+               the delete request will fail.
+  * Delete a repair run object identified by the given "id" path parameter.
+    Repair run and all the related repair segments will be deleted from the database.
+
+## Repair Schedule Resource
+
+* GET     /repair_schedule
+  * Expected query parameters:
+      * *clusterName*: Filter the returned schedule list based on the given
+        cluster name. (Optional)
+      * *keyspaceName*: Filter the returned schedule list based on the given
+        keyspace name. (Optional)
+  * Returns all repair schedules present in the Reaper
+
+* GET     /repair_schedule/{id}
+  * Expected query parameters: *None*
+  * Returns a repair schedule object identified by the given "id" path parameter.
+
+* POST    /repair_schedule
+  * Expected query parameters:
+    * *clusterName*: Name of the Cassandra cluster.
+    * *keyspace*: The name of the table keyspace.
+    * *tables*: The name of the targeted tables (column families) as comma separated list.
+                If no tables given, then the whole keyspace is targeted. (Optional)
+    * *owner*: Owner name for the schedule. This could be any string identifying the owner.
+    * *segmentCount*: Defines the amount of segments to create for scheduled repair runs. (Optional)
+    * *repairParallelism*: Defines the used repair parallelism for scheduled repair runs. (Optional)
+    * *intensity*: Defines the repair intensity for scheduled repair runs. (Optional)
+    * *incrementalRepair*: Defines if incremental repair should be done. [true/false] (Optional)
+    * *scheduleDaysBetween*: Defines the amount of days to wait between scheduling new repairs.
+                             For example, use value 7 for weekly schedule, and 0 for continuous.
+    * *scheduleTriggerTime*: Defines the time for first scheduled trigger for the run.
+                             If you don't give this value, it will be next mid-night (UTC).
+                             Give date values in ISO format, e.g. "2015-02-11T01:00:00". (Optional)
+
+* DELETE  /repair_schedule/{id}
+  * Expected query parameters:
+    * *owner*: Owner name for the schedule. If the given owner does not match the stored owner,
+               the delete request will fail.
+  * Delete a repair schedule object identified by the given "id" path parameter.
+    Repair schedule will get deleted only if there are no associated repair runs for the schedule.
+    Delete all the related repair runs before calling this endpoint.
+

src/docs/content/docs/backends/_index.md

@@ -0,0 +1,30 @@
++++
+[menu.docs]
+name = "Backends"
+identifier = "backends"
+weight = 10
++++
+
+# Backends
+
+Cassandra Reaper can be used with either an ephemeral memory storage or persistent database.
+
+For persistent relational database storage, you must either setup PostgreSQL or H2. You also need to set `storageType: database` in the config file.
+
+Reaper provides a number of backend storage options:
+
+* [In-Memory]({{<ref "memory.md" >}})
+* [Cassanda]({{<ref "cassandra.md">}})
+* [PostgresQL]({{<ref "postgres.md">}})
+* [H2]({{<ref "h2.md">}})
+
+Sample yaml files are available in the `src/packaging/resource` directory for each of the above storage backends:
+
+
+
+* cassandra-reaper-memory.yaml
+* cassandra-reaper-cassandra.yaml
+* cassandra-reaper-postgres.yaml
+* cassandra-reaper-h2.yaml
+
+For configuring other aspects of the service, see the available configuration options in the [Configuration Reference]({{<ref "configuration.md">}})

src/docs/content/docs/backends/cassandra.md

@@ -0,0 +1,49 @@
++++
+[menu.docs]
+name = "Cassandra"
+parent = "backends"
+weight = 4
++++
+
+# Cassandra Backend
+
+To use Apache Cassandra as the persistent storage for Reaper, the storageType setting must be set to cassandra in the Reaper configuration YAML file. In addition, the connection details for the Apache Cassandra cluster being used to store Reaper data must be specified in the configuration YAML file.
+
+For example:
+
+```yaml
+storageType: cassandra
+cassandra:
+  clusterName: "test"
+  contactPoints: ["127.0.0.1"]
+  keyspace: reaper_db
+  queryOptions:
+    consistencyLevel: LOCAL_QUORUM
+    serialConsistencyLevel: SERIAL
+```
+
+If you're using authentication or SSL:
+
+```yaml
+cassandra:
+  storageType: cassandra
+  clusterName: "test"
+  contactPoints: ["127.0.0.1"]
+  keyspace: reaper_db
+  authProvider:
+    type: plainText
+    username: cassandra
+    password: cassandra
+  ssl:
+    type: jdk
+```
+
+The Apache Cassandra backend is the only one that allows running several Reaper instances at once. This provides high availability and allows to repair multi DC clusters.
+
+
+To run Reaper using the Cassandra backend, create a reaper_db keyspace with an appropriate placement strategy. This is installation specific, and names of the data centers in the cluster that will host the Reaper data must be specified. For example:
+
+
+```none
+CREATE KEYSPACE reaper_db WITH replication = {'class': 'NetworkTopologyStrategy', 'datacenter1': 3};
+```

src/docs/content/docs/backends/h2.md

@@ -0,0 +1,23 @@
++++
+[menu.docs]
+name = "H2 (Local Storage)"
+parent = "backends"
+weight = 2
++++
+
+
+# H2 Backend
+
+To use H2 as the persistent storage for Reaper, the storageType setting must be set to database in the Reaper configuration YAML file. When using H2 storage, the database will be automatically created under the path configured in the configuration YAML file. An example of how to configure H2 as persistent storage for Reaper can be found in the cassandra-reaper-h2.yaml.
+
+
+```yaml
+storageType: database
+database:
+  # H2 JDBC settings
+  driverClass: org.h2.Driver
+  url: jdbc:h2:~/reaper-db/db;MODE=PostgreSQL
+  user:
+  password:
+
+```

src/docs/content/docs/backends/memory.md

@@ -0,0 +1,16 @@
++++
+[menu.docs]
+name = "In Memory"
+parent = "backends"
+weight = 1
++++
+
+# Memory Backend
+
+To use in memory storage as the storage type for Reaper, the `storageType` setting must be set to **memory** in the Reaper configuration YAML file. Note that the in memory storage is enabled by default.
+
+In memory storage is volatile and as such all registered cluster, column families and repair un information will be lost upon service restart. This storage setting is intended for testing purposes only.
+
+```yaml
+storageType: memory
+```

src/docs/content/docs/backends/postgres.md

@@ -0,0 +1,21 @@
++++
+[menu.docs]
+name = "Postgres"
+parent = "backends"
+weight = 3
++++
+
+# Postgres Backend
+
+To use PostgreSQL as the persistent storage for Reaper, the `storageType` setting must be set to **database** in the Reaper configuration YAML file. The schema will be initialized/upgraded automatically upon startup in the configured database. Ensure that the correct JDBC credentials are specified in the `cassandra-reaper.yaml` to allow object creation.
+
+
+```yaml
+storageType: database
+database:
+  # PostgreSQL JDBC settings
+  driverClass: org.postgresql.Driver
+  user: postgres
+  password: 
+  url: jdbc:postgresql://127.0.0.1/reaper
+```

src/docs/content/docs/community.md

@@ -0,0 +1,8 @@
++++
+[menu.docs]
+name = "Community"
+weight = 100
++++
+
+
+We have a [Mailing List](https://groups.google.com/forum/#!forum/tlp-apache-cassandra-reaper-users) and [Gitter chat](https://gitter.im/thelastpickle/cassandra-reaper) available.