docs: update documentation (#210)

* docs: add configuartion page

* docs: update installation page

* docs: add cli commands in tour pages

* docs: update guides with cli commands

* docs: add cli reference, update introduction page

* doc: update references

* chore: update dockerfile with server commands

* chore: update server commands in examples

Author: Chief-Rishab

Dockerfile.dev

@@ -14,4 +14,4 @@ RUN apk add ca-certificates
 # don't work well with musl libc that alpine uses
 RUN apk add libc6-compat
 
-CMD ["compass", "serve"]
+CMD ["compass", "server", "start"]

README.md

@@ -166,27 +166,27 @@ docker build . -t compass
 Before serving Compass app, we need to run the migration first. Run this docker command to migrate Compass.
 
 ```text
-$ docker run --rm --net compass_storage -p 8080:8080 -e ELASTICSEARCH_BROKERS=http://es:9200 -e DB_HOST=postgres -e DB_PORT=5432 -e DB_NAME=compass -e DB_USER=compass -e DB_PASSWORD=compass_password odpf/compass compass migrate
+$ docker run --rm --net compass_storage -p 8080:8080 -e ELASTICSEARCH_BROKERS=http://es:9200 -e DB_HOST=postgres -e DB_PORT=5432 -e DB_NAME=compass -e DB_USER=compass -e DB_PASSWORD=compass_password odpf/compass compass server migrate
 ```
 
 If you are using Compass binary, you can run this command.
 
 ```text
-./compass -elasticsearch-brokers "http://<broker-host-name>" -db-host "<postgres-host-name>" -db-port 5432 -db-name "<postgres-db-name>" -db-user "<postgres-db-user>" -db-password "<postgres-db-password> migrate"
+./compass -elasticsearch-brokers "http://<broker-host-name>" -db-host "<postgres-host-name>" -db-port 5432 -db-name "<postgres-db-name>" -db-user "<postgres-db-user>" -db-password "<postgres-db-password> server migrate"
 ```
 
 ## Serving locally
 
 Once the migration has been done, Compass server can be started with this command.
 
 ```text
-docker run --net compass_storage -p 8080:8080 -e ELASTICSEARCH_BROKERS=http://es:9200 -e DB_HOST=postgres -e DB_PORT=5432 -e DB_NAME=compass -e DB_USER=compass -e DB_PASSWORD=compass_password odpf/compass compass serve
+docker run --net compass_storage -p 8080:8080 -e ELASTICSEARCH_BROKERS=http://es:9200 -e DB_HOST=postgres -e DB_PORT=5432 -e DB_NAME=compass -e DB_USER=compass -e DB_PASSWORD=compass_password odpf/compass compass server start
 ```
 
 If you are using Compass binary, you can run this command.
 
 ```text
-./compass -elasticsearch-brokers "http://<broker-host-name>" -db-host "<postgres-host-name>" -db-port 5432 -db-name "<postgres-db-name>" -db-user "<postgres-db-user>" -db-password "<postgres-db-password> serve"
+./compass -elasticsearch-brokers "http://<broker-host-name>" -db-host "<postgres-host-name>" -db-port 5432 -db-name "<postgres-db-name>" -db-user "<postgres-db-user>" -db-password "<postgres-db-password> server start"
 ```
 
 ## Running tests

docs/docs/configuration.md

@@ -0,0 +1,287 @@
+# Configuration
+
+Compass binary contains both the CLI client and the server. Each has it's own configuration in order to run. Server configuration contains information such as database credentials, elastic search brokers, log severity, etc. while CLI client configuration only has configuration about which server to connect. 
+## Server Setup
+
+There are several approaches to setup Compass Server
+
+1. [Using the CLI](#using-the-cli)
+1. [Using the Docker](#using-the-docker)
+2. [Using the Helm Chart](#using-the-helm-chart)
+
+#### General pre-requisites
+
+- PostgreSQL (version 13 or above)
+- ElasticSearch v7 (optional)
+
+## Using the CLI
+### Using config file
+
+Create a config file with the following command 
+
+```sh
+$ compass config init
+```
+
+alternatively you can [use `--config` flag](#using---config-flag) to customize to config file location.
+
+You can also [use environment variables](#using-environment-variable) to provide the server configuration. 
+
+Setup up the Postgres database, and ElasticSearch instance and provide the details as shown in the example below.
+
+> If you're new to YAML and want to learn more, see [Learn YAML in Y minutes.](https://learnxinyminutes.com/docs/yaml/)
+
+Following is a sample server configuration yaml:
+
+```yaml title="compass.yaml"
+log_level: info                                 # debug|info|warning|error|fatal|trace|panic - default: info
+
+elasticsearch:
+    brokers: http://localhost:9200              #required
+
+db:
+    host: localhost                             #required
+    port: 5432                                  #required
+    name: compass                               #required
+    user: compass                               #required
+    password: compass_password                  #required
+    sslmode: disable                            #optional
+
+service:
+    host: localhost                             #required
+    port: 8080                                  #required    
+    identity:                                   
+        headerkey_uuid: Compass-User-UUID       #required
+        headerkey_email: Compass-User-Email     #optional
+        provider_default_name: shield           #optional
+    grpc:
+        port: 8081                              #required
+        max_send_msg_size: 33554432     
+        max_recv_msg_size: 33554432
+```
+### Using environment variable
+
+All the server configurations can be passed as environment variables using underscore _ as the delimiter between nested keys. 
+
+See [configuration reference](./reference/configuration.md) for the list of all the configuration keys.
+
+```sh title=".env"
+LOG_LEVEL=info
+ELASTICSEARCH_BROKERS=http://localhost:9200
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=compass
+DB_USER=compass
+DB_PASSWORD=compass_password
+DB_SSLMODE=disable
+SERVICE_HOST=localhost
+SERVICE_PORT=8080
+SERVICE_IDENTITY_HEADERKEY_UUID=Compass-User-UUID
+SERVICE_IDENTITY_HEADERKEY_EMAIL=Compass-User-Email
+SERVICE_IDENTITY_PROVIDER_DEFAULT_NAME=shield
+SERVICE_GRPC_PORT=8081
+SERVICE_GRPC_MAX_SEND_MSG_SIZE=33554432
+SERVICE_GRPC_MAX_RECV_MSG_SIZE=33554432
+```
+
+Set the env variable using export
+```bash
+$ export DB_PORT = 5432
+```
+### Starting the server
+
+Database migration is required during the first server initialization. In addition, re-running the migration command might be needed in a new release to apply the new schema changes (if any). It's safer to always re-run the migration script before deploying/starting a new release.
+
+To initialize the database schema, Run Migrations with the following command:
+```bash
+$ compass server migrate
+```
+
+To run the Compass server use command:
+
+```bash
+$ compass server start
+```
+
+#### Using `--config` flag
+
+```bash
+$ compass server migrate --config=<path-to-file> 
+```
+
+```bash
+$ compass server start --config=<path-to-file>
+```
+
+## Using the Docker 
+To run the Compass server using Docker, you need to have Docker installed on your system. You can find the installation instructions [here](https://docs.docker.com/get-docker/).
+
+You can choose to set the configuration using environment variables or a config file. The environment variables will override the config file.
+
+If you use Docker to build compass, then configuring networking requires extra steps. Following is one of doing it by running postgres and elasticsearch inside with `docker-compose` first.
+
+Go to the root of this project and run `docker-compose`.
+
+```bash
+$ docker-compose up
+```
+Once postgres and elasticsearch has been ready, we can run Compass by passing in the config of postgres and elasticsearch defined in `docker-compose.yaml` file.
+
+### Using config file
+Alternatively you can use the `compass.yaml` config file defined [above](#using-config-file) and run the following command.
+
+```bash
+$ docker run -d \
+    --restart=always \
+    -p 8080:8080 \
+    -v $(pwd)/compass.yaml:/compass.yaml \
+    --name compass-server \
+    odpf/compass:<version> \
+    server start -c /compass.yaml
+```
+
+### Using environment variables
+
+All the configs can be passed as environment variables using underscore `_` as the delimiter between nested keys. See the example as discussed [above](#using-environment-variable)
+
+Run the following command to start the server
+
+```bash
+$ docker run -d \
+    --restart=always \
+    -p 8080:8080 \
+    --env-file .env \
+    --name compass-server \
+    odpf/compass:<version> \
+    server start
+```
+
+## Using the Helm chart
+
+### Pre-requisites for Helm chart
+Compass can be installed in Kubernetes using the Helm chart from https://github.com/odpf/charts.
+
+Ensure that the following requirements are met:
+- Kubernetes 1.14+
+- Helm version 3.x is [installed](https://helm.sh/docs/intro/install/)
+
+### Add ODPF Helm repository
+
+Add ODPF chart repository to Helm:
+
+```
+helm repo add odpf https://odpf.github.io/charts/
+```
+
+You can update the chart repository by running:
+
+```
+helm repo update
+```
+
+### Setup helm values
+
+The following table lists the configurable parameters of the Compass chart and their default values.
+
+See full helm values guide [here](https://github.com/odpf/charts/tree/main/stable/compass#values)
+
+```yaml title="values.yaml"
+app:
+  image:
+    repository: odpf/compass
+    pullPolicy: Always
+    tag: "0.3.0"
+  container:
+    command:
+      - compass
+    args:
+      - server start
+    livenessProbe:
+      httpGet:
+        path: /ping
+        port: tcp
+    readinessProbe:
+      httpGet:
+        path: /ping
+        port: tcp
+
+  migration:
+    enabled: true
+    command:
+      - compass
+    args:
+      - server migrate
+
+  service:
+    annotations: {}
+
+  ingress:
+    enabled: true
+    annotations:
+      kubernetes.io/ingress.class: contour
+    hosts:
+      - host: compass.example.com
+        paths:
+          - path: /
+            pathType: ImplementationSpecific
+            backend:
+              service:
+                # name: backend_01
+                port:
+                  number: 80
+
+  config:
+    COMPASS_SERVICE_PORT: 8080
+    COMPASS_SERVICE_GRPC_PORT: 8081
+    # COMPASS_SERVICE_HOST: 0.0.0.0
+    # COMPASS_STATSD_ENABLED: false
+    # COMPASS_STATSD_PREFIX: compass
+    # COMPASS_NEWRELIC_ENABLED: false
+    # COMPASS_NEWRELIC_APPNAME: compass
+    # COMPASS_LOG_LEVEL: info
+
+  secretConfig: {}
+    # COMPASS_ELASTICSEARCH_BROKERS: ~
+    # COMPASS_STATSD_ADDRESS: ~
+    # COMPASS_NEWRELIC_LICENSEKEY: ~
+    # COMPASS_DB_HOST: ~
+    # COMPASS_DB_PORT: 5432
+    # COMPASS_DB_NAME: ~
+    # COMPASS_DB_USER: ~
+    # COMPASS_DB_PASSWORD: ~
+    # COMPASS_DB_SSLMODE: disable
+```
+
+And install it with the helm command line along with the values file:
+
+```bash
+$ helm install my-release -f values.yaml odpf/compass
+```
+
+## Client Initialisation
+
+Add client configurations in the same `~/compass.yaml` file in root of current directory. Open this file to configure client. 
+
+```yml
+client:
+    host: localhost:8081
+    serverheaderkey_uuid: Compass-User-UUID
+    serverheadervalue_uuid: [email protected]
+```
+
+#### Required Header/Metadata in API
+Compass has a concept of [User](./concepts/user.md). In the current version, all HTTP & gRPC APIs in Compass requires an identity header/metadata in the request. The header key is configurable but the default name is `Compass-User-UUID`.
+
+Compass APIs also expect an additional optional e-mail header. This is also configurable and the default name is `Compass-User-Email`. The purpose of having this optional e-mail header is described in the [User](./concepts/user.md) section.
+
+
+If everything goes ok, you should see something like this:
+```bash
+time="2022-04-27T09:18:08Z" level=info msg="compass starting" version=v0.2.0
+time="2022-04-27T09:18:08Z" level=info msg="connected to elasticsearch cluster" config="\"docker-cluster\" (server version 7.6.1)"
+time="2022-04-27T09:18:08Z" level=info msg="New Relic monitoring is disabled."
+time="2022-04-27T09:18:08Z" level=info msg="statsd metrics monitoring is disabled."
+time="2022-04-27T09:18:08Z" level=info msg="connected to postgres server" host=postgres port=5432
+time="2022-04-27T09:18:08Z" level=info msg="server started"
+```
+

docs/docs/guides/discussion.md

@@ -1,3 +1,6 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 # Discussion
 
 Discussion is a new feature in Compass. One could create a discussion and all users can put comment in it. Currently, there are three types of discussions `issues`, `open ended`, and `question and answer`. Depending on the type, the discussion could have multiple possible states. In the current version, all types only have two states: `open` and `closed`. A newly created discussion will always be assign an `open` state.
@@ -6,6 +9,23 @@ Discussion is a new feature in Compass. One could create a discussion and all us
 
 A discussion thread can be created with the Discussion API. The API contract is available [here](https://github.com/odpf/compass/blob/main/third_party/OpenAPI/compass.swagger.json).
 
+<Tabs groupId="cli" >
+<TabItem value="CLI" label="CLI">
+
+```bash
+$ compass discussion post --body=<filepath to discussion body>
+```
+
+```json
+{
+  "title": "The first discussion",
+  "body": "This is the first discussion thread in Compass",
+  "type": "openended"
+}
+```
+</TabItem>
+<TabItem value="HTTP" label="HTTP">
+
 ```bash
 $ curl --request POST 'http://localhost:8080/v1beta1/discussions' \
 --header 'Compass-User-UUID:[email protected]' \
@@ -15,15 +35,28 @@ $ curl --request POST 'http://localhost:8080/v1beta1/discussions' \
   "type": "openended"
 }'
 ```
+</TabItem>
+</Tabs>
 
 ## Fetching All Discussions
 
 The Get Discussions will fetch all discussions in Compass.
 
+<Tabs groupId="cli" >
+<TabItem value="CLI" label="CLI">
+
+```bash
+$ compass discussion list
+```
+</TabItem>
+<TabItem value="HTTP" label="HTTP">
+
 ```bash
 $ curl 'http://localhost:8080/v1beta1/discussions' \
 --header 'Compass-User-UUID:[email protected]'
 ```
+</TabItem>
+</Tabs>
 
 The response will be something like
 ```javascript