Improve doc and readme (#214)

* Better doc

* Fixes

* Move around dev instructions

* Don't need ToC anymore

* rewording

ADVANCED.md

@@ -0,0 +1,49 @@
+# Advanced usage
+
+### Infrastructure Setup
+
+First create and populate a .env file with the required variables:
+
+```bash
+cp deployments/kubehound/.env.tpl deployments/kubehound/.env
+```
+
+Edit the variables (datadog env `DD_*` related and `KUBEHOUND_ENV`):
+
+* `KUBEHOUND_ENV`: `dev` or `release` 
+* `DD_API_KEY`: api key you created from https://app.datadoghq.com/ website
+
+Note:
+* `KUBEHOUND_ENV=dev` will build the images locally
+* `KUBEHOUND_ENV=release` will use prebuilt images from ghcr.io 
+
+### Running KubeHound
+
+To replicate the automated command and run KubeHound step-by-step. First build the application:
+
+```bash
+make build
+```
+
+Next create a configuration file:
+
+```yaml
+collector:
+  type: live-k8s-api-collector
+telemetry:
+  enabled: true
+```
+
+A tailored sample configuration file can be found [here](./configs/etc/kubehound.yaml), a full configuration reference containing all possible parameters [here](./configs/etc/kubehound-reference.yaml). 
+
+Finally run the KubeHound binary, passing in the desired configuration:
+
+```bash
+bin/kubehound -c <config path>
+```
+
+Remember the targeted cluster must be set via `kubectx` or setting the `KUBECONFIG` environment variable. Additional functionality for managing the application can be found via:
+
+```bash
+make help
+```

DEVELOPER.md

@@ -1,8 +1,102 @@
-# Dev
+# Developer
+
+## Requirements
+
+To sucessufully build and run the test for kubehound, you need:
+
++ [Golang](https://go.dev/doc/install) `>= 1.22`
++ [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installing-with-a-package-manager)
++ [Kubectl](https://kubernetes.io/docs/tasks/tools/)
+
+## Build
+
+Build the application via:
+
+```bash
+make build
+```
+
+All binaries will be output to the [bin](./bin/) folder
+
+## Release build
+
+Build the release packages locally using [goreleaser](https://goreleaser.com/install):
+
+```bash
+make local-release
+```
+
+## Unit Testing
+
+The full suite of unit tests can be run locally via:
+
+```bash
+make test
+```
+
+## System Testing
+
+The repository includes a suite of system tests that will do the following:
++ create a local kubernetes cluster
++ collect kubernetes API data from the cluster
++ run KubeHound using the file collector to create a working graph database
++ query the graph database to ensure all expected vertices and edges have been created correctly
+
+The cluster setup and running instances can be found under [test/setup](./test/setup/)
+
+If you need to manually access the system test environment with kubectl and other commands, you'll need to set (assuming you are at the root dir):
+
+```bash
+cd test/setup/ && export KUBECONFIG=$(pwd)/.kube-config
+```
+
+### Environment variable:
+- `DD_API_KEY` (optional): set to the datadog API key used to submit metrics and other observability data.
+
+### Setup
+
+Setup the test kind cluster (you only need to do this once!) via:
+
+```bash
+make local-cluster-deploy
+```
+
+Then run the system tests via:
+
+```bash
+make system-test
+```
+
+To cleanup the environment you can destroy the cluster via:
+
+```bash
+make local-cluster-destroy
+```
+
+To list all the available commands, run:
+
+```bash
+make help
+```
+
+In case of conflict/error, or just if you want to free some of your RAM. You can destroy the backend stack dedicated to the system-test. 
+Simply run:
+```bash
+make system-test-clean
+```
+
+Note: if you are running on Linux but you don't want to run `sudo` for `kind` and `docker` command, you can overwrite this behavior by editing the following var in `test/setup/.config`:
+* `DOCKER_CMD="docker"` for docker command
+* `KIND_CMD="kind"` for kind command 
+
+### CI Testing
+
+System tests will be run in CI via the [system-test](./.github/workflows/system-test.yml) github action 
+
 
 ## Metrics and logs
 
-To have some indepth metrics and log correlation, all the components are now linked to datadog.  To configure it you just need to add your Datadog API key (`DD_API_KEY`) in the environment variable in the `deployments/kubehound/.env`. When the API key is configured, a docker will be created `kubehound-dev-datadog`. 
+To have some in-depth metrics and log correlation, all the components are now linked to datadog.  To configure it you just need to add your Datadog API key (`DD_API_KEY`) in the environment variable in the `deployments/kubehound/.env`. When the API key is configured, a docker will be created `kubehound-dev-datadog`. 
 
 All the information being gathered are available at:
 
@@ -15,7 +109,3 @@ To collect the metrics for Janusgraph an exporter from Prometheus is being used:
 They are exposed here:
 * Locally: http://127.0.0.1:8099/metrics
 * Datadog: https://app.datadoghq.com/metric/summary?filter=kubehound.janusgraph
-
-## Advanced command
-
-In case of conflict/error, or just if you want to free some of your RAM, you can use `make system-test-clean` to destroy the backend stack dedicated to the system-test.

Makefile

@@ -131,7 +131,7 @@ thirdparty-licenses: ## Generate the list of 3rd party dependencies and write to
 .PHONY: local-wiki
 local-wiki: ## Generate and serve the mkdocs wiki on localhost
 	poetry install || pip install mkdocs-material mkdocs-awesome-pages-plugin markdown-captions
-	poetry run mkdocs serve || mksdocs serve
+	poetry run mkdocs serve || mkdocs serve
 
 .PHONY: local-release
 local-release: ## Generate release packages locally via goreleaser