Development

Development

Welcome to the development documentation for the k8s-ephemeral-environments platform. This section provides everything contributors need to get started, understand the codebase, and submit quality contributions.

Overview

The k8s-ephemeral-environments platform consists of several components:

k8s-ephemeral-environments/
+-- .github/
|   +-- actions/          # Reusable composite actions
|   +-- workflows/        # CI/CD workflows
+-- charts/               # Helm charts
|   +-- k8s-ee-app/       # Main application chart
|   +-- k8s-ee-*/         # Database subchart packages
+-- demo-app/             # Demo application (NestJS API + React Web)
|   +-- packages/
|       +-- api/          # NestJS backend
|       +-- web/          # React frontend
+-- docs/                 # Documentation
+-- k8s/                  # Kubernetes manifests
+-- scripts/              # Utility scripts

Development Sections

Developer-Onboarding

Complete guide for new team members:

• Prerequisites - Required tools and versions
• First-time setup - Clone, install, run locally
• Cluster access - SSH and kubeconfig setup
• Observability - Grafana dashboards and log queries
• Development workflow - Branch, code, test, PR flow
• Quick reference - Essential kubectl and helm commands

Contributing

Guidelines for making contributions:

• Code style - TypeScript conventions, linting, formatting
• Branch naming - Patterns for features, fixes, hotfixes
• Commit messages - Conventional commits format
• Pull request process - From branch to merge
• Testing requirements - Coverage expectations
• Documentation - When and how to update docs

Quick Start for Contributors

1. Set Up Your Environment

# Clone the repository
git clone https://github.com/koder-cat/k8s-ephemeral-environments.git
cd k8s-ephemeral-environments

# Install demo app dependencies
cd demo-app
pnpm install

# Start local development environment
pnpm dev:local

2. Create a Feature Branch

git checkout -b feat/us-XXX-description

3. Make Changes and Test

cd demo-app
pnpm dev        # Start dev servers
pnpm test       # Run tests
pnpm lint       # Check code style

4. Submit a Pull Request

git commit -m "feat(scope): add new feature"
git push -u origin feat/us-XXX-description
gh pr create

5. Verify in Preview Environment

Once CI completes, your PR gets an automatic preview environment:

• URL: k8s-ee-pr-{number}.k8s-ee.genesluna.dev
• Bot comments on PR with the link
• Check Grafana for logs and metrics

Development Tools

Tool	Purpose	Required Version
Node.js	JavaScript runtime	22+
pnpm	Package manager	9+
Docker	Container runtime	Latest
kubectl	Kubernetes CLI	1.31+
Helm	Kubernetes package manager	3.16+
GitHub CLI	GitHub operations	Latest

Project Structure

Demo Application

The demo app showcases the platform capabilities:

Package	Technology	Purpose
@demo-app/api	NestJS	Backend API with metrics, health checks
@demo-app/web	React + Vite	Frontend with simulator and dashboards

Helm Charts

Chart	Purpose
k8s-ee-app	Main application chart
k8s-ee-postgresql	PostgreSQL via CloudNativePG
k8s-ee-mongodb	MongoDB via Community Operator
k8s-ee-redis	Redis deployment
k8s-ee-minio	MinIO (S3-compatible storage)
k8s-ee-mariadb	MariaDB deployment

GitHub Actions

Component	Purpose
Composite Actions	Modular, reusable CI/CD steps
Reusable Workflows	Complete PR environment lifecycle
Self-hosted Runners	In-cluster job execution

Testing Strategy

Type	Tool	Coverage Target
Unit Tests	Jest/Vitest	50% minimum
Integration Tests	Jest + Supertest	API endpoints
E2E Tests	Playwright	Critical flows

Run all tests:

cd demo-app
pnpm test           # All tests
pnpm test:cov       # With coverage report
pnpm test:watch     # Watch mode

Key Documentation

Document	Purpose
Developer-Onboarding	New contributor setup
Contributing	Contribution guidelines
Configuration-Reference	k8s-ee.yaml schema
Service-Development	Database integration patterns
Security-and-Access-Control	Security architecture

Need Help?

• Check existing GitHub Issues
• Review the User-Guides section for operational guides
• Consult the Architecture section for system design

---

Related Pages

• Developer-Onboarding - Complete setup guide for new developers
• Contributing - Contribution guidelines and processes
• Architecture - System architecture overview
• Configuration-Reference - Configuration schema reference
• Home - Documentation home page