docs: update docs

.github/workflows/commitlint.yaml

@@ -12,4 +12,4 @@ on:
 
 jobs:
   validate:
-    uses: defenseunicorns/uds-common/.github/workflows/callable-commitlint.yaml@730d22c6e061153d525a6d6f932e108ae952bd46 # v1.23.0
+    uses: defenseunicorns/uds-common/.github/workflows/callable-commitlint.yaml@0cfdcaa2dbe7a539dec471edbb081c88b06fe8ec # v1.24.2

.github/workflows/lint.yaml

@@ -12,5 +12,5 @@ on:
 
 jobs:
   validate:
-    uses: defenseunicorns/uds-common/.github/workflows/callable-lint.yaml@730d22c6e061153d525a6d6f932e108ae952bd46 # v1.23.0
+    uses: defenseunicorns/uds-common/.github/workflows/callable-lint.yaml@0cfdcaa2dbe7a539dec471edbb081c88b06fe8ec # v1.24.2
     secrets: inherit

.github/workflows/release.yaml

@@ -26,7 +26,7 @@ jobs:
       matrix:
         flavor: [upstream, unicorn]
         architecture: [amd64, arm64]
-    uses: defenseunicorns/uds-common/.github/workflows/callable-publish.yaml@730d22c6e061153d525a6d6f932e108ae952bd46 # v1.23.0
+    uses: defenseunicorns/uds-common/.github/workflows/callable-publish.yaml@0cfdcaa2dbe7a539dec471edbb081c88b06fe8ec # v1.24.2
     with:
       flavor: ${{ matrix.flavor }}
       options: --set BASE_REPO="ghcr.io/uds-packages"

.github/workflows/scan.yaml

@@ -18,5 +18,5 @@ jobs:
       packages: read # Allows reading the content of the repository's packages.
       id-token: write # Allows authentication to Rapidfort via OIDC.
       pull-requests: write # Allows writing the scan results comment to the pull request.
-    uses: defenseunicorns/uds-common/.github/workflows/callable-scan.yaml@730d22c6e061153d525a6d6f932e108ae952bd46 # v1.23.0
+    uses: defenseunicorns/uds-common/.github/workflows/callable-scan.yaml@0cfdcaa2dbe7a539dec471edbb081c88b06fe8ec # v1.24.2
     secrets: inherit # Inherits all secrets from the parent workflow.

.github/workflows/test.yaml

@@ -31,7 +31,7 @@ jobs:
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: test-flavor
-        uses: defenseunicorns/uds-common/.github/actions/test-flavor@730d22c6e061153d525a6d6f932e108ae952bd46 # v1.23.0
+        uses: defenseunicorns/uds-common/.github/actions/test-flavor@0cfdcaa2dbe7a539dec471edbb081c88b06fe8ec # v1.24.2
         id: test-flavor
     outputs:
       upgrade-flavors: ${{ steps.test-flavor.outputs.upgrade-flavors }}
@@ -43,7 +43,7 @@ jobs:
       matrix:
         type: [install, upgrade]
         flavor: [upstream, unicorn]
-    uses: defenseunicorns/uds-common/.github/workflows/callable-test.yaml@730d22c6e061153d525a6d6f932e108ae952bd46 # v1.23.0
+    uses: defenseunicorns/uds-common/.github/workflows/callable-test.yaml@0cfdcaa2dbe7a539dec471edbb081c88b06fe8ec # v1.24.2
     with:
       timeout: 30
       options: --set BASE_REPO="ghcr.io/uds-packages"

README.md

@@ -1,40 +1,63 @@
-# UDS Package Reference Package
+# UDS Reference Package
 
-This package is designed to serve as a reference of what a UDS Package may look like. This package is not intended to be *functional* and should only serve to show what the layout of a UDS Package can look like. 
+This repository serves as a practical, working example of a well-structured UDS Package.
 
-The application itself is a simple web app built with Go. This can currently be found in the `src` directory. The function of the app is a page that can write and get queries from a bundled `postgres` database.
+Inside the `.github` directory, you will find a fully runnable Go-based web application that reads and writes to a Postgres database.  This repository can be referenced alongside the [UDS Documentation](https://uds.defenseunicorns.com/), as a reference guide for building, configuring, and testing own UDS packages.
 
-### Demonstration
-The following should be demonstrated within this UDS Package:
-- Dependencies Pulled into a UDS Bundle
-- Keycloak SSO Configuration
-- Prometheus Service Monitoring
-- Helm Overrides
-- UDS Config Chart Templates
-- Istio Virtual Service Creation
-- Network Policy Creation
-- Playwright UI Testing
+> [!NOTE]
+> **The primary purpose of this repository is to demonstrate UDS Package architecture, layout, and best practices. The application's specific features are secondary.**
 
+## What This Demonstrates
 
-## Pre-requisites
+This repository should aim to provide functional examples of the following:
 
-The Reference Package Package expects to be deployed on top of [UDS Core](https://github.com/defenseunicorns/uds-core) with the dependencies listed below being configured prior to deployment.
+* **Bundle Integration:** Pulling dependencies into a UDS Bundle.
+* **Authentication:** Keycloak SSO configuration.
+* **Observability:** Prometheus service monitoring integration.
+* **Configuration:** Helm overrides and UDS Config chart templates.
+* **Networking & Security:** Istio Virtual Service and Network Policy creation.
+* **Testing:** Playwright UI testing.
 
-#### Postgres Database
-This package requires a postgres database instance. It is suggested to pull this into the `uds-bundle` by using the `postgres-operator` uds package.
-#### Monitoring
-To demonstrate monitoring, the `k3d-core-demo` will need to be installed instead of `k3d-core-slim-dev`.
 
-## Releases
+## Prerequisites
 
-The released packages can be found in [ghcr](https://github.com/uds-packages/reference-package/pkgs/container/reference-package).
+This reference package is designed to be deployed on top of [UDS Core](https://github.com/defenseunicorns/uds-core). Please ensure the following dependencies are configured prior to deployment:
 
-## UDS Tasks (for local dev and CI)
+* **Postgres Database:** The Go application requires a Postgres instance. We recommend bringing this into your `bundle/uds-bundle` by using the `postgres-operator` UDS package.
+* **Monitoring:** To successfully demonstrate the monitoring features, you will need to install the `k3d-core-demo` bundle rather than the `k3d-core-slim-dev` bundle.
+
+> [!TIP]
+> `k3d-core-demo` is set as the default k3d bundle if you run `uds run default` in the root directory.
+
+## Quick Start
+### UDS Tasks (for local dev and CI)
 
 *For local dev, this requires you install [uds-cli](https://github.com/defenseunicorns/uds-cli?tab=readme-ov-file#install)
 
+The UDS Tasks can be found in the `tasks.yaml`
 > [!TIP]
 > To get a list of tasks to run you can use `uds run --list`!
+### Deployment
+#### If you already have UDS Core installed
+
+This will create the package, create the test-bundle, then deploy in the k3d cluster.
+```bash
+uds run dev
+```
+
+#### If you do not have UDS Core installed
+
+This will stand up the k3d cluster, create the package, create the test-bundle, then deploy in the k3d cluster.
+```bash
+uds run default
+```
+#### Access the WebUI
+Once the app is deployed, it can be accessed in the web browser at https://reference-package.uds.dev
+
+## Releases
+
+The released packages can be found in [ghcr](https://github.com/uds-packages/reference-package/pkgs/container/reference-package).
+
 
 ## Contributing
 

docs/configuration.md

@@ -1,5 +1,69 @@
 # Configuration
 
-Reference Package in this package is configured through [Reference Package UDS package](#UDS_PACKAGE_REPO#) as well as a UDS configuration chart that supports the following:
+The Reference Package is configured using the [application's Helm chart](https://github.com/uds-packages/reference-package/tree/main/.github/container-and-chart/helm/chart), alongside the `uds-reference-package` UDS config chart.
 
-## Additional Configuration Info Follows
+## Bundle Overrides
+
+Use bundle overrides in `bundle/uds-bundle.yaml` to configure the Database, SSO, and Monitoring.
+
+```yaml
+overrides:
+  reference-package:
+    reference-package:
+      values:
+        - path: database
+          value:
+            secretName: "reference-package-postgres"
+            secretKey: "PASSWORD"
+        - path: sso
+          value:
+            enabled: true
+            secretName: reference-package-sso
+        - path: monitoring
+          value:
+            enabled: true
+
+```
+
+## UDS Config Chart Values
+
+### PostgreSQL Database
+
+The underlying Go application requires a database connection string provided via a Kubernetes secret.
+
+If you are using the [uds-package-postgres-operator](https://github.com/uds-packages/postgres-operator) in your bundle, the `uds-reference-package-config` chart (located in `./chart`) will create the secret, via the below values:
+
+```yaml
+postgres:
+  username: "reference"
+  # Note: Specifying password as anything other than "" will not use the existingSecret
+  password: ""
+  existingSecret:
+    name: "reference-package.reference-package.pg-cluster.credentials.postgresql.acid.zalan.do"
+    passwordKey: password
+    usernameKey: username
+  host: "pg-cluster.postgres.svc.cluster.local"
+  dbName: "reference"
+  # Example: "?connect_timeout=10&sslmode=disable"
+  connectionOptions: "?sslmode=disable"
+  # Set to false to use external postgres
+  internal: true
+  selector:
+    cluster-name: pg-cluster
+  namespace: postgres
+  port: 5432
+```
+
+### Single Sign-On
+
+Setting `sso.enabled: true` in the UDS config chart overrides tells the package to generate an SSO secret.
+
+This relies on the UDS Operator's built-in secret templating. You can read more about how this works in the [UDS SSO Templating Documentation](https://uds.defenseunicorns.com/reference/configuration/single-sign-on/sso-templating/).
+
+### Monitoring
+
+Setting `monitoring.enabled: true` configures the package to expose metrics to Prometheus. More information can be found here: [Monitoring and Metrics](https://uds.defenseunicorns.com/reference/configuration/observability/monitoring-metrics/)
+
+## Package Custom Resources (CR)
+
+For further information regarding the UDS Package Custom Resource (CR), defined in the `chart/templates/uds-package.yaml`, the full specification can be found in the [UDS Package CR Documentation](https://uds.defenseunicorns.com/reference/configuration/custom-resources/exemptions-v1alpha1-cr/).

docs/go-app.md

@@ -0,0 +1,32 @@
+# Reference Package Web Application & Helm Chart
+
+The underlying application for this UDS package is a lightweight Go web service. It features a simple user interface designed specifically to demonstrate reading and writing data to a Postgres database.
+
+While the application code itself is relatively simple, its primary purpose is to demonstrate integration with various components within the UDS ecosystem.
+
+## Directory Structure & Architecture
+
+You will find the application source code and deployment manifests in the following locations:
+
+* **Go Application Source & Dockerfile:** `.github/container-and-chart/docker`
+* **Helm Charts:** `.github/container-and-chart/helm`
+
+> [!NOTE]
+> In a standard development scenario, it may make more sense for the Go App and Helm Charts to live in a `src/` directory and is built at runtime. However, the application and its Helm charts are intentially decoupled into this structure. This allows the Docker container and Helm charts to be published independently of the UDS package.
+> By doing this, engineers can pull and use our container and Helm chart for their own purposes. It also provides a realistic demonstration of how a UDS package pulls external artifacts via the `common/zarf.yaml` and `.zarf.yaml` files.
+
+## Update & Publishing Workflow
+
+The UDS package relies on the published artifacts in GHCR. If you make changes to the Go application or the Helm chart, you must publish the new versions to GHCR before updating the UDS package. If you update the `zarf.yaml`, image tags in `<flavor>-values.yaml`, etc., before the new artifacts finish publishing, your local Zarf builds and CI pipelines will fail when trying to pull the non-existent versions.
+
+Follow these steps when making changes to the Go application or chart:
+
+1. Update the Go source code or adjust the Helm chart templates as needed.
+2. If needed, bump the respective versions in `.github/container-and-chart/docker/version.txt` and `.github/container-and-chart/helm/Chart.yaml`.
+3. Commit and push your changes. This will trigger the `.github/workflows/release-container-and-charts.yaml` GitHub Action, which builds and publishes the new container image and Helm chart to GHCR. This workflow is set to only run on PRs to the following:
+```yaml
+    paths:
+      - ".github/container-and-chart/**"
+      - ".github/workflows/release-container-and-charts.yaml"
+```
+4. Ensure the GitHub Action completes successfully and the new artifacts are visible in the repository's GHCR page.