Skip to main content

Install with GitOps

Production installations are reconciled from the customer's GitOps repository. Pin an explicitly published chart version in the release declaration and keep environment-specific settings in a reviewed values file. Never track latest.

Use the production values example as the starting point:

global:
  existingSecret: loadouthq-runtime

config:
  appBaseUrl: https://loadouthq.example.com
  apiPublicUrl: https://loadouthq.example.com
  corsOrigin: https://loadouthq.example.com
  sessionCookieSecure: true
  platformAdminEmail: admin@example.com
  registrationEnabled: false
  orgCreationEnabled: false
  localAuthEnabled: true

license:
  existingSecret: loadouthq-license
  secretKey: license.lhq-license

imagePullSecrets:
  - name: loadouthq-registry

ingress:
  enabled: true
  className: nginx
  host: loadouthq.example.com
  tls:
    enabled: true
    secretName: loadouthq-tls

api:
  replicaCount: 2
  podDisruptionBudget:
    enabled: true

web:
  replicaCount: 2
  podDisruptionBudget:
    enabled: true

Store this as values.production.yaml beside the GitOps release declaration. Keep the chart version, OCI source, namespace, reconciliation policy, and values-file reference in that declaration. The exact resource depends on the customer's controller, such as Flux or Argo CD.

Argo CD with the OCI chart​

Use Argo CD's native OCI source support. The Application must reference the complete chart artifact with the oci:// scheme, set path: ., and pin the chart version without the Git tag's v prefix. Do not use Helm CLI's parent push URL (.../charts) as the Application repository URL.

For the private GitLab registry, create a read-only deploy token with read_registry, then register the complete artifact repository with Argo CD:

argocd repo add oci://registry.gitlab.com/asfadev/loadouthq/charts/loadouthq \
  --type oci \
  --name loadouthq \
  --username "$LOADOUTHQ_REGISTRY_USERNAME" \
  --password "$LOADOUTHQ_REGISTRY_PASSWORD"

Apply the Argo CD Application example after replacing the version, URLs, administrator email, routing settings, and Secret names. The important OCI fields are:

source:
  repoURL: oci://registry.gitlab.com/asfadev/loadouthq/charts/loadouthq
  targetRevision: X.Y.Z
  path: .

LoadoutHQ publishes the chart with Helm's standard application/vnd.cncf.helm.chart.content.v1.tar+gzip layer media type. The release pipeline pulls the pushed artifact back through Helm OCI before recording the release, catching an unreadable or misaddressed chart immediately.

Create runtime, registry, and optional license Secrets through the customer's external-secret or sealed-secret workflow as described in Configuration and Licensing. Do not commit Secret values, registry tokens, or license files to Git.

Ingress is enabled in the production example. For Gateway API, layer the HTTPRoute values example after the production values file. The referenced Gateway must permit Route attachment from the LoadoutHQ namespace; TLS is configured on its listener.

Commit the release declaration, values files, and secret references through the customer's normal review process. Let the GitOps controller reconcile the release, then verify the result:

kubectl -n loadouthq rollout status deployment/loadouthq-loadouthq-api
kubectl -n loadouthq rollout status deployment/loadouthq-loadouthq-web
curl -fsS https://loadouthq.example.com/health/ready
curl -fsS https://loadouthq.example.com/api/v1/license/status

Resource names include both release and chart names. Confirm them with kubectl -n loadouthq get deploy when choosing another release name.

First administrator and OIDC​

If no license was mounted, open /license, sign in or register with exactly platformAdminEmail, then upload the vendor-issued file at /admin/license. Other bootstrap registrations remain blocked in activation-only mode.

After activation:

  1. Confirm customer, license ID, source, and expiry on License.
  2. Open Identity providers from the user menu.
  3. Register the callback URL shown by LoadoutHQ with the identity provider.
  4. Test discovery before enabling the provider.
  5. Complete one OIDC sign-in in a private browser window.
  6. Disable local registration if it was temporarily enabled.

Verify core behavior​

Check both health endpoints, then exercise organization isolation, folder permissions, upload and processing, download, token creation, and MCP access. Ready pods alone are not a successful handoff.