Pack Catalog

Browse your cluster's pack registry as a gallery — and install a pack with one click.
A Nebari Software Pack that lists every pack published to an OCI registry (default quay.io/nebari/charts) as cards, then installs a chosen one by committing an ArgoCD Application straight into your GitOps repository. A pack that installs packs.

What is it? · What it does · Screenshots · Quick Start · Configuration · Architecture · Examples

Status: Under active development as part of Nebari Infrastructure Core (NIC). APIs, chart values, and generated manifest shapes may change without notice while pre-1.0.

What is the Pack Catalog?

The Pack Catalog is a Nebari Software Pack that turns your cluster's pack registry into a browsable gallery and lets you install a pack with one click. It deploys the way every other pack does (a Helm chart carrying a NebariApp), and it drives the same GitOps install path that Nebari's tooling uses under the hood — so it is a pack that installs packs.

It exists because discovering "which packs can I run, and how do I install one?" should be a gallery and a button, not a hand-edited ArgoCD manifest. The differentiator over a read-only dashboard is that last step: the catalog writes an ArgoCD Application into your GitOps repo and commits it, then nudges ArgoCD to reconcile — installing the pack through ArgoCD's own model rather than out of band.

Curious how the pieces fit together? See the architecture further down.

What It Does

Capability	Description
Registry discovery	Enumerates packs from a Quay/OCI registry (default quay.io/nebari/charts) and resolves each pack's versions.
Card gallery	Renders every pack as a card with name, description, category, maturity level, and latest version. Search, filter (category/level), and sort the gallery.
Installed-state	Flags packs already present in the cluster with their ArgoCD health/sync, and disables re-install.
Metadata enrichment	Best-effort reads each pack's pack-metadata.yaml for display name, description, and maturity.
One-click install	Generates an ArgoCD Application and commits it to your GitOps repo's apps/ directory.
OCI or git source	Sources the chart from oci://quay.io/nebari/charts/<name> (default) or github.com/nebari-dev/<name>.
ArgoCD nudge	Annotates the root app-of-apps to reconcile now, then polls the installed app to Healthy.
Preview / dry-run	Renders the exact Application it would commit without touching any repo.

Screenshots

One-click install previews and renders the exact ArgoCD Application before anything is committed:

Screenshots are regenerated by the Playwright harness in test/e2e/ (npm run screenshots) and refreshed in CI by screenshots.yml.

Quick Start

Browse locally (read-only, no cluster)

See the gallery against the live Nebari registry with no credentials:

make -f dev/Makefile run
# open http://localhost:8080/

This runs in dry-run mode: it lists packs from quay.io/nebari/charts and, on Preview, renders the exact Application it would commit — without touching any repo. (CATALOG_DEMO=true serves a fixed offline list instead, used for the screenshots above.)

Operator-managed install (default)

On a Nebari cluster, drop examples/argocd-application.yaml into your GitOps repo's apps/ directory (edit the catalog.gitops.* values to point at that same repo). ArgoCD syncs the chart and the nebari-operator wires routing/TLS/auth from the NebariApp.

Standalone install (without the Nebari Operator)

The chart installs standalone with the NebariApp disabled; reach the UI via port-forward or your own Ingress.

helm repo add nebari https://nebari-dev.github.io/helm-repository
helm repo update
helm install nebari-catalog-pack nebari/nebari-catalog-pack \
  --namespace nebari-system --create-namespace \
  -f examples/standalone-values.yaml

Or from a local checkout:

helm install nebari-catalog-pack ./chart -n nebari-system --create-namespace -f examples/standalone-values.yaml

gitops-token (referenced in the values files) is an existing Secret with a token key holding a git PAT that can push to the GitOps repo. Without a gitops.repoURL the catalog still deploys, but installs are disabled (read-only gallery).

Configuration

Every value maps to a CATALOG_* environment variable (see internal/config). Full list in chart/values.yaml.

Value	Default	Purpose
catalog.registry.namespace	nebari	registry org/namespace to browse
catalog.registry.chartPrefix	charts	OCI repo prefix for charts
catalog.gitops.repoURL	""	GitOps repo to commit Applications into (empty = read-only)
catalog.gitops.path	""	cluster sub-dir; apps go to <path>/apps/
catalog.gitops.tokenSecret.name	""	Secret holding a git PAT
catalog.gitops.sshKeySecret.name	""	Secret holding an SSH key (alternative to PAT)
catalog.install.preferOCI	true	source generated Apps from OCI vs git
catalog.install.domain	""	base domain for installed packs' hostnames
catalog.argocd.rootApp	nebari-root	app-of-apps to nudge after a commit
catalog.dryRun	false	preview manifests without committing

The catalog can install software cluster-wide, so the chart defaults nebariapp.auth.enabled=true restricted to the admin group.

RBAC

The chart creates a Role/RoleBinding in the ArgoCD namespace granting the catalog only what it needs:

Resource	Verbs	Purpose
applications.argoproj.io	get, list, watch, patch	nudge the root app to reconcile and poll installed app health

Git credentials are supplied via a referenced Secret and read from the environment at start — never written into the GitOps repo. The container runs non-root with a read-only root filesystem.

Development

make -f dev/Makefile web           # build the React SPA into web/dist
make -f dev/Makefile build         # build the binary (embeds the SPA) into ./bin
make -f dev/Makefile test          # go test ./...
make -f dev/Makefile vet
make -f dev/Makefile web-typecheck # tsc --noEmit
make -f dev/Makefile image         # docker build (builds the SPA in a stage)
make -f dev/Makefile helm-lint
cd test/e2e && npm install && npm run screenshots   # regenerate UI screenshots

To run the catalog on a real cluster locally (kind + Helm, standalone), see docs/dev-cluster.md (make -f dev/Makefile cluster-create cluster-deploy); the full-platform install path is exercised in CI by integration.yml.

The frontend is a React + TypeScript single-page app (web/) built with Vite + Tailwind v4, using components from the Nebari design system shadcn registry (@nebari). The Go server exposes a JSON API (/api/*) and serves the built SPA embedded in the binary — no runtime external requests. A committed placeholder keeps go build working before the frontend is built; the real build happens in CI, the Docker image stage, and make web.

Integration tests

integration.yml boots a full NIC platform with action-nebari-sandbox (profile: platform) and exercises the pack against a real cluster in two layers: (1) deploy-and-Healthy — builds the image and deploys the chart onto the platform via the add-software-pack sub-action, asserting Application/nebari-catalog-pack reaches Healthy; (2) the real install path — runs the catalog against the sandbox's live file:// GitOps repo + ArgoCD, triggers a genuine install through the API the SPA uses and captures live screenshots with the Playwright harness in test/e2e/ (npm run screenshots:live), then asserts the catalog committed an Application that ArgoCD then created. The live screenshots are captured under docs/screenshots/live/ (committed on main runs; artifact-only on PRs). It runs on PRs touching the payload, on main, and on demand — heavier than ci.yml, which stays cluster-free.

Project Structure

cmd/catalog            entrypoint: load config, wire dependencies, serve HTTP
internal/config        env-driven configuration (CATALOG_*)
internal/registry      Quay/OCI discovery, metadata enrichment, demo fixtures
internal/gitops        ArgoCD Application builder + go-git committer
internal/argocd        dynamic-client refresh nudge + Application status poll
internal/installer     orchestration: resolve -> render -> commit -> nudge -> wait
internal/server        JSON API (/api/*) + serves the embedded SPA
web/                   React + TS single-page app (Vite, Tailwind v4, @nebari)
chart/                 Helm chart packaging the service as a pack
examples/              ArgoCD Application + values for operator/standalone installs
test/e2e/              Playwright screenshot harness
docs/                  architecture notes + screenshots

Architecture

ArgoCD does not write to git — the catalog does, and ArgoCD syncs. Full design in docs/architecture.md.

sequenceDiagram
    actor User
    participant Catalog as catalog service
    participant Git as GitOps repo
    participant Argo as ArgoCD
    User->>Catalog: click Install (htmx POST)
    Catalog->>Git: commit apps/<name>.yaml (go-git)
    Catalog->>Argo: PATCH application/<root> refresh=normal
    Git-->>Argo: app-of-apps watches apps/*.yaml
    Argo->>Argo: create + sync child Application (chart + NebariApp)
    Catalog->>Argo: poll child Application status
    Argo-->>Catalog: Healthy / Synced
    Catalog-->>User: result fragment

Loading

Contributing

git clone https://github.com/nebari-dev/nebari-catalog-pack
cd nebari-catalog-pack
make -f dev/Makefile test

Issues and PRs welcome. See the architecture notes, the examples, and pack-metadata.yaml for how this pack surfaces on the Nebari pack dashboard. Contributing and code-of-conduct guidance is inherited org-wide from nebari-dev/.github.

License

Apache 2.0 — same as the rest of the Nebari Infrastructure Core stack.