Troubleshooting

Caddy can't get a TLS cert

DNS must point at the control-plane host before startup, otherwise the HTTP-01 challenge fails and Caddy backs off.

docker compose logs caddy

Look for obtaining certificate followed by an error. Fix the DNS A record, then docker compose restart caddy.

Control plane 500s on tenant provision

Three common causes:

# 1. Kubeconfig not readable inside the container
docker compose exec control-plane cat /app/.kube/config

# 2. kubectl can't reach the cluster
docker compose exec control-plane kubectl get nodes

# 3. Helm chart fails to lint
docker compose exec control-plane helm lint /app/charts/nucleus-moodle

If kubectl get nodes works but provisioning still fails, check docker compose logs control-plane for the actual Helm error.

Tenant provisions but DNS or TLS is broken

Two suspects:

• Wildcard DNS. *.your-domain must resolve to the cluster ingress IP. Check dig <random>.your-domain returns the ingress LB.

• ClusterIssuer. The chart references letsencrypt-prod by default. If you named yours something else, override via Helm values:

  ingress:
    clusterIssuer: my-issuer-name

Bootstrap admin skipped

If the entrypoint can't find BOOTSTRAP_ADMIN_EMAIL + BOOTSTRAP_ADMIN_PASSWORD in the environment, it skips the seed. Set them in .env.production and re-run docker compose up -d control-plane — the entrypoint upserts on every boot, so re-running is safe.

Backups not appearing

Check three things in order:

1. The StorageClass supports volume snapshots: kubectl get volumesnapshotclasses.
2. The CronJob ran and didn't error: kubectl logs -n <tenant-ns> -l job-name=....
3. The label selector matches: snapshots are tagged nucleus.local/tenant=<slug> and nucleus.local/snapshot-of=moodledata.

Tenant ingress 502

Usually the Moodle pod isn't ready. kubectl describe pod -n <tenant-ns> will show whether it's still pulling the image, failing a probe, or stuck on a config init container.

Where to escalate

• Support for licence and commercial questions.
• The private GitHub issues repo for bug reports with reproductions.
• The customer Slack tier for install / upgrade / protocol questions and operational gotchas.