Cashu Mint Operator

A Kubernetes operator for running CDK mintd with a single CashuMint custom resource. The operator manages the mint Deployment, generated config, Services, optional PostgreSQL, backups, ingress/TLS, Orchard, metrics, and sidecars so users can operate a Cashu mint with standard Kubernetes workflows instead of hand-managed YAML.

Documentation

• Docs: docs/index.md (rendered with mkdocs, see mkdocs.yml)
• Getting started: docs/getting-started.md
• Deployment guide: docs/deployment-guide.md
• Payment processors: docs/payment-processors.md
• Sample catalog: docs/samples.md
• API reference: docs/api-reference.md
• Troubleshooting: docs/troubleshooting.md

What the operator manages

• Deployment, ConfigMap, and Service for every mint
• PVCs for SQLite and Orchard state
• Auto-provisioned PostgreSQL Secret, Service, and StatefulSet
• S3 backup CronJob and restore Job for auto-provisioned PostgreSQL
• Ingress and optional cert-manager Certificate
• Optional Orchard companion resources
• Optional management RPC TLS Secret generation
• Optional PodMonitor when Prometheus metrics are enabled
• Optional gRPC payment processor sidecars and LDK node sidecars

Quick start

Install the latest release from git.cashu.dev:

TAG=$(curl -fsSL https://git.cashu.dev/api/v1/repos/asmo/cashu-operator/releases/latest \
  | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
kubectl apply -f "https://git.cashu.dev/asmo/cashu-operator/releases/download/${TAG}/install.yaml"

Or pin a version:

kubectl apply -f https://git.cashu.dev/asmo/cashu-operator/releases/download/v0.3.2/install.yaml

Deploy the minimal sample:

kubectl create namespace cashu-mints
kubectl apply -n cashu-mints \
  -f https://git.cashu.dev/asmo/cashu-operator/raw/branch/main/config/samples/mint_v1alpha1_cashumint_minimal.yaml
kubectl get cashumints -n cashu-mints -w

Access the mint:

kubectl -n cashu-mints port-forward svc/cashumint-minimal 8085:8085
curl http://localhost:8085/v1/info

Sample manifests

Scenario	Manifest
Minimal quick start (fakeWallet + SQLite)	mint_v1alpha1_cashumint_minimal.yaml
Annotated starter template	mint_v1alpha1_cashumint.yaml
Auto-provisioned PostgreSQL	mint_v1alpha1_cashumint_postgres_auto.yaml
External PostgreSQL	mint_v1alpha1_cashumint_external_postgres.yaml
LND backend	mint_v1alpha1_cashumint_lnd.yaml
CLN backend	mint_v1alpha1_cashumint_cln.yaml
External gRPC payment processor	mint_v1alpha1_cashumint_grpc_processor_external.yaml
Arkade Lightning sidecar processor	mint_v1alpha1_cashumint_arkade_processor.yaml
Spark/Breez or Stripe sidecar processors	mint_v1alpha1_cashumint_spark_breez.yaml, mint_v1alpha1_cashumint_stripe_processor.yaml
Orchard	mint_v1alpha1_cashumint_orchard_sqlite.yaml, mint_v1alpha1_cashumint_orchard_postgres.yaml
Auth, Redis cache, limits, metrics	mint_v1alpha1_cashumint_auth_httpcache.yaml
LDK node sidecar	mint_v1alpha1_cashumint_ldk_node.yaml
Production-style reference	mint_v1alpha1_cashumint_production.yaml

Development

Local development with Tilt + k3d

The recommended local workflow uses the dedicated k3d cluster defined in ctlptl-config.yaml.

make tilt-up

That command creates or updates a dedicated cashu-operator-dev k3d cluster with a local registry, switches kubectl to k3d-cashu-operator-dev, and starts Tilt against that context.

Once Tilt is running:

1. codegen regenerates manifests and deepcopy code when the API changes.
2. unit-tests is available as a manual Tilt resource for make test.
3. demo-mint is available as a manual Tilt resource to apply a minimal CashuMint from config/dev/.
4. demo-arkade-mint builds /Users/asm/git/cashu-arkade-lightning-procesor, imports cashu-arkade-lightning-procesor:dev into k3d, and applies the Arkade processor demo from config/dev/arkade/.

The Arkade demo image build defaults can be overridden with ARKADE_PROCESSOR_DIR, ARKADE_PROCESSOR_IMAGE, ARKADE_PROCESSOR_DOCKERFILE, and ARKADE_PROCESSOR_PLATFORM.

To inspect the demo mint after triggering demo-mint:

kubectl -n cashu-mints port-forward svc/cashumint-minimal 8085:8085
curl http://localhost:8085/v1/info

To inspect the Arkade processor demo after triggering demo-arkade-mint:

kubectl -n cashu-arkade port-forward svc/cashumint-arkade 8085:8085
curl http://localhost:8085/v1/info

To stop the local loop:

make tilt-down
make dev-cluster-delete

make build            # Build controller binary
make run              # Run controller locally against active kubeconfig
make dev-cluster-up   # Create/update the dedicated local k3d dev cluster
make tilt-up          # Start Tilt against the local k3d dev cluster
make tilt-down        # Stop Tilt and remove Tilt-managed resources
make dev-reset        # Tear down Tilt-managed resources and delete the dev cluster
make test             # Run unit tests
make test-e2e         # Run end-to-end tests (provisions Kind cluster)
make lint             # Run golangci-lint
make manifests        # Regenerate CRDs, RBAC, webhook configs
make generate         # Regenerate DeepCopy methods
make build-installer  # Generate dist/install.yaml

License

Apache 2.0 -- see LICENSE.