Using AI Coding Assistants

If you use an AI coding assistant — Claude Code, GitHub Copilot, Cursor, or similar — this page gives it static context about your CompactHive environment via a CLAUDE.md/AGENTS.md-style file in your repo.

Prefer a live connection instead of a static file? See Connect Your AI Agent for the MCP server — it lets a supported agent query your actual tenant (apps, services, build status, logs) instead of you keeping a file like this up to date by hand. Both approaches work; use whichever fits your workflow.

Template

For the live MCP + Git workflow, use one CompactHive token from Settings → Agent access, with Read + deploy + push code. Follow Connect Your AI Agent for local credential setup; never paste the token into chat or an instructions file.

Create a CLAUDE.md (or AGENTS.md) in your project root:

# Project Infrastructure (CompactHive)

## Environment
- Platform: CompactHive (self-hosted managed infra)
- Tier: Basic / Team / Pro / Business / Enterprise
- Slug: YOUR_SLUG

## URLs
- Portal: https://app.compacthive.io
- CI/CD: https://YOUR_SLUG-ci.compacthive.dev
- App URL pattern: https://YOUR_SLUG-APP_NAME.compacthive.dev
- Registry: registry.compacthive.dev

## Git provider
- Forgejo (built-in, default) or GitHub (beta — manual connect + Settings "Set Up" for CI).

## CI/CD
- Engine: Woodpecker CI (Kubernetes backend)
- Pipeline file: .woodpecker.yaml
- Build: Kaniko (daemonless, no Docker daemon)
- Registry auth: auto-injected Woodpecker secrets (registry_url, registry_user, registry_password)

## Database
- Engine: PostgreSQL 17 (CNPG operator)
- Host: pg-<tenant-id>-rw.NAMESPACE.svc.cluster.local, port 5432
- Connection string: see portal Connect or Developer Guide page

## Deploying apps
1. Push to Forgejo (or a connected GitHub repo, beta) — Woodpecker + Kaniko builds the image.
2. Image goes to registry.compacthive.dev/PROJECT/REPO:TAG.
3. Deploy via the portal Apps page or POST /api/portal/apps.
4. URL: https://YOUR_SLUG-APP_NAME.compacthive.dev

## Key constraints
- Kubernetes namespace isolation — no cluster-admin access.
- ResourceQuota limits CPU/memory/storage per tier; app count is capped per tier too.
- No Docker daemon in CI — use Kaniko, not `docker build`.
- TLS is terminated at the edge; apps receive plain HTTP on their configured port.

## Documentation
- https://docs.compacthive.io

Giving an assistant task-specific context

Task	What to tell the assistant
Write a Dockerfile	Target amd64/arm64, keep the image small, EXPOSE the right port
Write a CI pipeline	Engine Woodpecker, builder Kaniko (--insecure, registry secrets via from_secret) — see CI/CD Pipelines
Connect to the database	Host pg-<tenant-id>-rw, standard PostgreSQL driver, connection string from the Connect page
Debug a deployment	Check the portal Resources page for pod status, and the Logs viewer for app logs
Set up monitoring	Grafana at YOUR_SLUG-grafana.compacthive.dev (Monitoring service); Prometheus scrapes your pods automatically once Monitoring is enabled