Chore: More documentation (#30)

* fix config default value Signed-off-by: Joshua Irmer <[email protected]> * add more documentation Signed-off-by: Joshua Irmer <[email protected]> * fix typo Signed-off-by: Joshua Irmer <[email protected]> * Apply suggestions from code review Co-authored-by: Joshua Mühlfort <[email protected]> Signed-off-by: Joshua Irmer <[email protected]> --------- Signed-off-by: Joshua Irmer <[email protected]> Signed-off-by: Joshua Irmer <[email protected]> Co-authored-by: Joshua Mühlfort <[email protected]>
SovereignCloudStack · Jul 4, 2024 · d7afe22 · d7afe22
1 parent 687a28d
commit d7afe22
Show file tree

Hide file tree

Showing 6 changed files with 83 additions and 2 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,22 @@
+# Configuration
+
+Configuration can be done by environment variables or flags to the binary.
+
+Code to the configuration can be found at `internal/app/config/config.go`.
+
+| Environment key                        | Flag                         | Description                                  | Type         | Default              |
+| -------------------------------------- | ---------------------------- | -------------------------------------------- | ------------ | -------------------- |
+| **General settings**                   |                              |                                              |              |                      |
+| STATUS_PAGE_PROVISIONING_FILE          | --provisioning-file          | YAML file containing the initial values      | Path         | ./provisioning.yaml  |
+| STATUS_PAGE_SHUTDOWN_TIMEOUT           | --shutdown-timeout           | Timeout to gracefully stop the server        | Duration     | 10s                  |
+| STATUS_PAGE_VERBOSE                    | -v / --verbose               | Increase log level                           | Counter      | 0                    |
+| **Server settings**                    |                              |                                              |              |                      |
+| STATUS_PAGE_SERVER_ADDRESS             | --server-address             | API server listen address                    | String       | :3000                |
+| STATUS_PAGE_SERVER_ALLOWED_ORIGINS     | --server-allowed-origins     | List of allowed CORS origins                 | String Array | 127.0.0.1, localhost |
+| STATUS_PAGE_SERVER_SWAGGER_UI_ENABLED  | --server-swagger-ui-enabled  | Enable the swagger UI at `/swagger`          | Boolean      | False                |
+| **Database settings**                  |                              |                                              |              |                      |
+| STATUS_PAGE_DATABASE_CONNECTION_STRING | --database-connection-string | PostgreSQL connection string                 | String       |                      |
+| **Metrics settings**                   |                              |                                              |              |                      |
+| STATUS_PAGE_METRICS_ADDRESS            | --metrics-address            | Enable and set metrics server listen address | String       |                      |
+| STATUS_PAGE_METRICS_NAMESPACE          | --metrics-namespace          | Metrics namespace                            | String       | status_page          |
+| STATUS_PAGE_METRICS_SUBSYSTEM          | --metrics-subsystem          | Metrics subsystem name                       | String       | api                  |
diff --git a/docs/contribute.md b/docs/contribute.md
@@ -0,0 +1,3 @@
+# Contribute
+
+Contributions are welcome at [SovereignCloudStack/status-page-api](https://github.com/SovereignCloudStack/status-page-api).
diff --git a/docs/overview.md b/docs/overview.md
@@ -0,0 +1,7 @@
+# Overview
+
+The `status-page-api` repository strives to provide a reference implementation of the concepts being outlined by [`status-page-openapi`](https://github.com/SovereignCloudStack/status-page-openapi).
+
+For the implementation [`go`](https://go.dev/) was used, as rational see the [decision record](https://github.com/SovereignCloudStack/standards/blob/main/Standards/scs-0401-v1-status-page-reference-implementation-decision.md#programming-language).
+
+Code under the `pkg/` directory, is considered as public reference or even library code to implement your own API server, while code in `internal/` is implementation specific to this application, but can serve as reference, too.
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,44 @@
+# Quickstart
+
+See [requirements](./requirements.md)
+
+## Run as container
+
+The quickest way to start working with the API server, is to run the container directly.
+
+```bash
+docker run --rm --network host -e STATUS_PAGE_DATABASE_CONNECTION_STRING="host=localhost user=postgres dbname=postgres port=5432 password=debug sslmode=disable" -e STATUS_PAGE_VERBOSE=3 registry.scs.community/status-page/status-page-api:latest
+```
+
+## Compile and run the binary
+
+Compiling the binary and running it is equally easy.
+
+```bash
+go build -o /bin/status-page-api cmd/status-page-api/main.go
+
+STATUS_PAGE_DATABASE_CONNECTION_STRING="host=localhost user=postgres dbname=postgres port=5432 password=debug sslmode=disable" STATUS_PAGE_VERBOSE=3 ./bin/status-page-api
+```
+
+## Running tests
+
+The status page API server tests it's API handler and database code with a plethora of tests. These tests can be run with `go`.
+
+```bash
+go test ./...
+```
+
+Furthermore test can be run to create a coverage profile.
+
+```bash
+go test -coverprofile coverage.out ./...
+```
+
+This cover profile can be used to analyze code coverage
+
+```bash
+# per function coverage
+go tool cover -func coverage.out
+# HTML representation of tested code
+go tool cover -html coverage.out
+```
diff --git a/docs/requirements.md b/docs/requirements.md
@@ -0,0 +1,5 @@
+# Requirements
+
+The status page API server requires a [PostgreSQL](https://www.postgresql.org/) database.
+
+When compiling the API server itself, a [Go installation](https://go.dev/doc/install) is required.
diff --git a/internal/app/config/config.go b/internal/app/config/config.go
@@ -148,8 +148,8 @@ func setFlags() {
 
 	pflag.String(databaseConnectionString, databaseConnectionStringDefault, "Database connection string.")
 
-	pflag.String(metricsNamespace, metricsNamespace, "Metrics namespace.")
-	pflag.String(metricsSubsystem, metricsSubsystem, "Metrics sub system name.")
+	pflag.String(metricsNamespace, metricsNamespaceDefault, "Metrics namespace.")
+	pflag.String(metricsSubsystem, metricsSubsystemDefault, "Metrics sub system name.")
 	pflag.String(metricsAddress, metricsAddressDefault, "Metrics server listen address.")
 
 	pflag.String(serverAddress, serverAddressDefault, "Server listen address.")