Development Setup¶

Set up your local environment for Language Operator development.

Prerequisites¶

Go 1.21+ - Download
Docker - For building images
kubectl - Kubernetes CLI
Helm 3.8+ - Package manager
k3d or kind (optional) - Local Kubernetes cluster
make - Build automation

Clone the Repository¶

git clone https://github.com/language-operator/language-operator
cd language-operator

Install Git Hooks¶

Install pre-commit hooks for validation:

./scripts/setup-hooks

This installs hooks that:

Enforce conventional commit messages
Validate generated files are staged
Run basic linting

Development Commands¶

All Go work runs from src/:

Build¶

cd src
make build       # compile operator binary

Test¶

cd src
make test        # fmt + vet + all tests
make fmt         # go fmt only
make vet         # go vet only

Integration Tests¶

cd src
make integration-test  # requires setup-envtest

Integration tests run against a real Kubernetes API server via controller-runtime's envtest.

Run Single Test¶

cd src
go test ./controllers/... -run TestLanguageAgentController -v

Integration Tests Only¶

cd src
go test -tags integration -v ./controllers/...

Modifying CRD Types¶

After changing types in src/api/v1alpha1/:

cd src
make generate   # regenerate zz_generated.deepcopy.go
make helm-crds  # regenerate CRD YAMLs and copy to chart/crds/

Important: Always stage generated files together with type changes:

git add src/api/v1alpha1/zz_generated.deepcopy.go
git add src/config/crd/bases/
git add chart/crds/

The pre-commit hook enforces this.

Helm Chart Validation¶

cd chart
helm lint .
helm template language-operator . --debug

Documentation¶

Generate CRD Documentation¶

cd src
make docs   # generates src/docs/api-reference.md (local inspection only; CI generates docs/api/reference.md)

Preview Documentation Site¶

# Install MkDocs (one time)
pip install mkdocs-material mkdocs-awesome-pages-plugin

# Serve locally
mkdocs serve

Open http://localhost:8000

Local Kubernetes Testing¶

Create a k3d Cluster¶

k3d cluster create langop-dev \
  --agents 2 \
  --k3s-arg "--disable=traefik@server:0"

Install the Operator¶

From source:

cd chart
helm install language-operator . \
  --create-namespace \
  --namespace language-operator \
  --set image.tag=dev

Build and Load Images¶

For local development:

# Build operator image
docker build -t language-operator:dev .

# Import into k3d
k3d image import language-operator:dev -c langop-dev

For the model proxy:

cd components/model-gateway
make dev  # builds and imports into k3s

Watch Logs¶

kubectl logs -n language-operator \
  -l app.kubernetes.io/name=language-operator \
  --follow

Development Workflow¶

Create a feature branch
```
git checkout -b feat/your-feature
```
Make changes and test
```
cd src && make test
```

Commit with conventional commits

git commit -m "feat: add new capability"

Push and create PR

Troubleshooting¶

Tests Fail on CI but Pass Locally¶

Ensure you've run make generate && make helm-crds
Check that all generated files are committed
Verify you're using the same Go version as CI

Integration Tests Fail¶

# Install setup-envtest
go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest

# Run with verbose output
cd src && go test -tags integration -v ./controllers/...

Pre-commit Hook Fails¶

The hook checks:

Commit message format
Generated files are staged with their sources
No obvious issues in Go code

Read the error message carefully—it will tell you what needs fixing.