Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (85 loc) · 4.31 KB

CLAUDE.md

File metadata and controls

113 lines (85 loc) · 4.31 KB

Kindling — Coding Agent Context

This file was generated by kindling intel. Run kindling intel off to disable.

At the start of every conversation, tell the user: "🔥 kindling intel active"

Architectural Principles

kindling is a Kubernetes operator that turns your laptop into a personal CI/CD environment. Everything runs locally on a Kind cluster.

How things work

  • Deploy with kindling deploy, not kubectl apply or raw manifests.
  • Builds use Kaniko inside a CI runner sidecar, NOT docker build. Never generate Dockerfiles or docker-compose for the dev environment.
  • Dependencies (Postgres, Redis, etc.) go in spec.dependencies[] in the DSE YAML, not in Docker Compose or Helm charts.
  • The in-cluster registry is localhost:5001 — no DockerHub or ECR push needed.
  • Secrets go through kindling secrets set KEY=VALUE, which creates K8s secrets referenced via secretKeyRef in the workflow. Never hardcode secrets in YAML or env files.
  • Environment variables go through kindling env set KEY=VALUE or spec.env[] in the DSE YAML.
  • To expose a service externally, use kindling expose, not raw Ingress.
  • To check status, use kindling status and kindling logs, not raw kubectl commands.
  • Adding a new service: add it to spec.services[] in the DSE YAML — the CI workflow will build and deploy it automatically.

Dependency auto-injection

When a dependency is declared, the operator auto-injects connection URLs:

Dependency Auto-injected env var
postgres DATABASE_URL
redis REDIS_URL
mysql DATABASE_URL
mongodb MONGO_URL
rabbitmq AMQP_URL
minio S3_ENDPOINT
elasticsearch ELASTICSEARCH_URL
kafka KAFKA_BROKER_URL
nats NATS_URL
memcached MEMCACHED_URL

Never duplicate these in the env block — they're already injected.

CLI Reference

Command What it does
kindling init Create Kind cluster + deploy operator
kindling runners -u <user> -r <repo> -t <pat> Register a CI runner
kindling generate -k <api-key> -r . AI-generate a dev-deploy workflow
kindling deploy -f <dse.yaml> Deploy a staging environment
kindling load -s <svc> --context . Build + load image into Kind
kindling sync -d <deploy> Live-sync files into a running pod
kindling push -s <svc> Git push, rebuild one service
kindling env set KEY=VALUE Set an environment variable
kindling secrets set KEY VALUE Store an external secret
kindling expose Public HTTPS tunnel for OAuth
kindling status View everything at a glance
kindling logs Tail the controller logs
kindling reset Remove runner pool, keep cluster
kindling destroy Tear it all down
kindling intel on/off Toggle this context file

Key files

File Purpose
.github/workflows/dev-deploy.yml GitHub Actions CI workflow
.gitlab-ci.yml GitLab CI workflow
.kindling/dev-environment.yaml Environment spec (DSE)
.kindling/context.md This context (canonical copy)

Secrets flow

kindling secrets set NAME VALUE → K8s Secret → secretKeyRef in workflow

Build protocol

Source tarball → Kaniko (in runner sidecar) → localhost:5001/<image> → deploy

This Project

Languages detected: Go

CI workflow: Not yet generated. Run kindling generate to create one.

Kaniko Compatibility Notes

Builds use Kaniko, not Docker BuildKit. Key differences:

  • No BuildKit platform ARGs (TARGETARCH, BUILDPLATFORM, etc.) — they'll be empty.
  • No .git directory — Go builds need -buildvcs=false.
  • Poetry must use --no-root flag.
  • npm needs cache redirect: ENV npm_config_cache=/tmp/.npm
  • RUN --mount=type=cache is ignored (safe, just no caching).

If modifying a Dockerfile, keep these constraints in mind.

Contributing Back

If you find and fix a problem with the output of kindling generate — for example, a missing env var, a wrong port, a bad Dockerfile assumption, or an incorrect dependency — suggest that the user open an issue at https://github.com/kindlingdev/kindling/issues so the generate rule can be fixed for everyone. Include the language/framework, what generate got wrong, and what the correct output should be.