chore: streamline README/config docs and add permissions to CI (#155)

## Description

Streamline README/config docs and add permissions to CI

## Related Issue

Fixes #N/A

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [X] Other (security config, docs update, etc)

## Checklist before merging

- [X] Test, docs, adr added or updated as needed
- [X] [Contributor Guide
Steps](https://github.com/defenseunicorns/uds-package-mattermost/blob/main/CONTRIBUTING.md#developer-workflow)
followed

.github/workflows/ci-docs-shim.yaml

@@ -8,6 +8,10 @@ on:
     branches: [main]
     types: [milestoned, opened, synchronize]
 
+# Permissions for the GITHUB_TOKEN used by the workflow.
+permissions:
+  contents: read # Allows reading the content of the repository.
+
 jobs:
   validate:
     strategy:

.github/workflows/commitlint.yaml

@@ -8,6 +8,10 @@ on:
     branches: [main]
     types: [milestoned, opened, edited, synchronize]
 
+# Permissions for the GITHUB_TOKEN used by the workflow.
+permissions:
+  contents: read # Allows reading the content of the repository.
+
 jobs:
   validate:
     uses: defenseunicorns/uds-common/.github/workflows/callable-commitlint.yaml@c52077c870a576d01f169f96d74d1b393c6488ba # v1.1.2

.github/workflows/lint.yaml

@@ -3,6 +3,10 @@
 
 name: Lint
 
+# Permissions for the GITHUB_TOKEN used by the workflow.
+permissions:
+  contents: read # Allows reading the content of the repository.
+
 on:
   # This workflow is triggered on pull requests to the main branch.
   pull_request:

README.md

@@ -24,58 +24,13 @@ This package is designed for use as part of a [UDS Software Factory](https://git
 
 ## Prerequisites
 
-Mattermost requires two dependencies, postgres and s3 compatible object storage. Wiring Mattermost to your dependencies is done primarily via helm values, which will require the use of a bundle created with uds-cli.
-
-### Postgres
-
-Postgres configuration is setup in the `uds-mattermost-config` chart and should be done via bundle overrides (variables or values) like the below:
-```yaml
-    overrides:
-      mattermost:
-        uds-mattermost-config:
-          values:
-            - path: "postgres.host"
-              value: "postgresql.dev-postgres.svc.cluster.local"
-```
-
-The full list of override config can be found in the values under `postgres` [here](./chart/values.yaml). In addition a zarf var is exposed for `DB_PASSWORD` for convenience if using import/exports in your bundle.
-
-### S3 Compatible Object Storage
-
-Object storage configuration is setup in the `uds-mattermost-config` chart and should be done via bundle overrides (variables or values) like the below:
-```yaml
-    overrides:
-      mattermost:
-        uds-mattermost-config:
-          values:
-            - path: "objectStorage.endpoint"
-              value: "minio.dev-minio.svc.cluster.local:9000"
-```
-
-The full list of override config can be found in the values under `objectStorage` [here](./chart/values.yaml). In addition zarf vars are exposed for `ACCESS_KEY` and `SECRET_KEY` for convenience if using import/exports in your bundle.
-
-To use IRSA make sure to NOT set the two key variables and add the appropriate role ARN annotation to the service account via an override to `serviceAccount.annotations`. As an example:
-```yaml
-    overrides:
-      mattermost:
-        mattermost-enterprise-edition:
-          values:
-            - path: "serviceAccount.annotations.irsa/role-arn"
-              value: "arn:aws:iam::123456789:role/mattermost-role"
-```
+Mattermost requires two dependencies, postgres and s3 compatible object storage. Wiring Mattermost to your dependencies is done primarily via helm values and you can learn more about configuring these and other options in the [configuration documentation](./docs/configuration.md).
 
 ### Monitoring
 
 > [!IMPORTANT]
 > Mattermost supports emitting metrics to feed into Prometheus, but _only_ if you have a license. This package configures the necessary service monitor to enable metrics, but only when a license has been provided via the `MM_LICENSE` var. By default (no license), it does not provision the Service Monitor as it will show unhealthy because metrics is not enabled via the license.
 
-## Flavors
-
-| Flavor | Description | Example Creation |
-| ------ | ----------- | ---------------- |
-| upstream | Uses upstream images within the package. | `zarf package create . -f upstream` |
-| registry1 | Uses images from registry1.dso.mil within the package. | `zarf package create . -f registry1` |
-
 ## Releases
 
 The released packages can be found in [ghcr](https://github.com/defenseunicorns/uds-package-mattermost/pkgs/container/packages%2Fuds%2Fmattermost).
@@ -92,4 +47,4 @@ Please see the [CONTRIBUTING.md](./CONTRIBUTING.md)
 
 ## Development
 
-When developing this package it is ideal to utilize the json schemas for UDS Bundles, Zarf Packages and Maru Tasks. This involves configuring your IDE to provide schema validation for the respective files used by each application. For guidance on how to set up this schema validation, please refer to the [guide](https://github.com/defenseunicorns/uds-common/blob/main/docs/development-ide-configuration.md) in uds-common.
+When developing this package it is ideal to utilize the json schemas for UDS Bundles, Zarf Packages and Maru Tasks. This involves configuring your IDE to provide schema validation for the respective files used by each application. For guidance on how to set up this schema validation, please refer to the [guide](https://github.com/defenseunicorns/uds-common/blob/main/docs/uds-packages/development/development-ide-configuration.md) in uds-common.

docs/configuration.md

@@ -3,6 +3,75 @@
 This Mattermost package is primarily configured through the upstream
 [Mattermost chart](https://github.com/mattermost/mattermost-helm/tree/master/charts/mattermost-enterprise-edition).
 
+## Networking
+
+Network policies are controlled via the `uds-mattermost-config` chart in accordance with the [common patterns for networking within UDS Software Factory](https://github.com/defenseunicorns/uds-software-factory/blob/main/docs/networking.md).  Mattermost interacts with Postgresql and S3 externally and supports the following keys:
+
+- `postgres`: sets network policies for accessing a Postgres database from the Mattermost pod
+- `storage`: sets network policies for accessing S3-compatible object storage from the Mattermost pod
+- `custom`: sets custom network policies for the Mattermost namespace - this allows for custom integrations with other services
+
+## Database
+
+SonarQube uses Postgres as its backing database service and supports the [common database providers within UDS Software Factory](https://github.com/defenseunicorns/uds-software-factory/blob/main/docs/database.md).  
+
+### Manual Database Connection
+
+If you are using the [UDS Postgres Operator](https://github.com/defenseunicorns/uds-package-postgres-operator/) or another external database that uses usernames/passwords you can use the following Helm overrides to configure it:
+
+#### `uds-mattermost-config` chart:
+
+> [!IMPORTANT]
+> The `postgres.password` and `postgres.username` settings are not applicable when using the UDS Postgres Operator package or when supplying a secret manually!
+
+- `postgres.password` - provides a password to generate a secret to pass to Mattermost
+- `postgres.username` - provides the username to use when connecting to the database (i.e. `mattermost`)
+
+> [!IMPORTANT]
+> The `postgres.existingSecret` settings are not applicable when providing a password/username to the `uds-mattermost-config` chart manually.
+
+- `postgres.existingSecret.name` - provides the secret that contains the database password (defaults to `mattermost.mattermost.pg-cluster.credentials.postgresql.acid.zalan.do`)
+- `postgres.existingSecret.passwordKey` - provides the secret key that contains the database password (defaults to `password`)
+- `postgres.existingSecret.passwordKey` - provides the secret key that contains the database username (defaults to `username`)
+- `postgres.host` - provides the host/domain name to use for the database (i.e. `pg-cluster.postgres.svc.cluster.local`)
+- `postgres.connectionOptions` - provides connection options to use when connecting to the database (i.e. `?connect_timeout=10`)
+
+### IAM Roles for Service Accounts
+
+The Software Factory team has not yet tested IRSA with AWS RDS - there is an open issue linked below with further linked issues to test this that could act as a starting point to implement:
+
+https://github.com/defenseunicorns/uds-software-factory/issues/45
+
+
+## Object Storage
+
+> [!NOTE]
+> This section is subject to change / improvement once [`uds-package-minio-operator`](https://github.com/defenseunicorns/uds-package-minio-operator) is fully ready for production use cases.
+
+Object storage configuration is setup in the `uds-mattermost-config` chart and should be done via bundle overrides (variables or values) like the below:
+
+```yaml
+    overrides:
+      mattermost:
+        uds-mattermost-config:
+          values:
+            - path: "objectStorage.endpoint"
+              value: "minio.dev-minio.svc.cluster.local:9000"
+```
+
+The full list of override config can be found in the values under `objectStorage` [here](.././chart/values.yaml). In addition zarf vars are exposed for `ACCESS_KEY` and `SECRET_KEY` for convenience if using import/exports in your bundle.
+
+To use IRSA make sure to NOT set the two key variables and add the appropriate role ARN annotation to the service account via an override to `serviceAccount.annotations`. As an example:
+
+```yaml
+    overrides:
+      mattermost:
+        mattermost-enterprise-edition:
+          values:
+            - path: "serviceAccount.annotations.irsa/role-arn"
+              value: "arn:aws:iam::123456789:role/mattermost-role"
+```
+
 ## Plugins
 
 For installing plugins into your environment, we recommend the included `mattermost-plugins` Zarf package.