Skip to content

Developer Starter Kit

This guide helps developers set up a local AKKO environment, build custom images, add services, and run the test suite.

Local Dev Setup (k3d + Helm)

Prerequisites

  • Docker Desktop with at least 16 GB RAM allocated
  • k3d (lightweight Kubernetes in Docker)
  • Helm 3.x
  • kubectl
  • macOS ARM or Linux x86_64

Quick Start

# 1. Create the k3d cluster
bash helm/scripts/k3d-create.sh

# 2. Build all custom images
bash helm/scripts/build-images.sh

# 3. Deploy AKKO
bash helm/scripts/deploy.sh

The deploy.sh script handles everything: cluster creation, image building, Helm install with the dev values, and Keycloak realm import.

Manual Deploy

If you prefer step-by-step control:

# Create k3d cluster
k3d cluster create akko --servers 1 --agents 2 \
  --port "443:443@loadbalancer" --port "80:80@loadbalancer"

# Build and import custom images
bash helm/scripts/build-images.sh

# Helm install
helm install akko helm/akko/ \
  -f helm/examples/values-dev.yaml \
  --set-file akko-keycloak.realm.data=helm/examples/realm-akko-k3d.json

Dev Values

The file helm/examples/values-dev.yaml contains development-specific overrides: lower resource limits, debug logging, and local storage classes.

Building Custom Images

AKKO uses 5 custom Docker images, all tagged with 2026.03:

Image Dockerfile Description
akko-jupyterhub docker/jupyterhub/Dockerfile Hub image
akko-notebook docker/jupyterhub/Dockerfile.notebook User notebook (Python, R, Julia, Quarto, code-server)
akko-spark docker/spark/Dockerfile Spark with Iceberg + AWS JARs
akko-postgres docker/postgres/Dockerfile PostgreSQL with PostGIS + pgvector
akko-cockpit branding/cockpit/Dockerfile Portal with health proxies

Build all images at once:

bash helm/scripts/build-images.sh

Build a single image:

docker build -t akko-notebook:2026.03 -f docker/jupyterhub/Dockerfile.notebook .
k3d image import akko-notebook:2026.03 -c akko

No :latest tags

All images must use pinned version tags (e.g., 2026.03). The :latest tag is mutable and breaks reproducibility.

Adding a New Service

AKKO has a strict 15-step checklist for adding any service. This ensures full integration with auth, monitoring, catalog, and documentation.

See the full checklist in Adding a Service. Key steps:

  1. Create a Helm sub-chart in helm/akko/charts/
  2. Add dependency in helm/akko/Chart.yaml
  3. Add values in helm/akko/values.yaml and helm/examples/values-dev.yaml
  4. Register OAuth client in keycloak/realm-akko.json
  5. Add Cockpit card (HTML + health check + nginx proxy)
  6. Create EN + FR documentation pages
  7. Update docs/mkdocs.yml navigation
  8. Update README service count

All steps in the same commit

CI enforces that service changes include documentation updates. A PR missing doc pages will fail.

Running Tests

AKKO has 184 tests across 12 categories.

Full Test Suite

bash tests/run-all.sh

Estimated time: ~45 minutes for the full suite.

Fast Validation

bash tests/run-all.sh --fast

Estimated time: ~10 minutes. Covers health checks, auth, and basic data tests.

Test Categories

Category Tool What it Tests
Health Shell All 33+ service endpoints respond
Auth pytest Keycloak SSO flow, token exchange
RBAC pytest Role-based access across services
Theme Playwright Keycloak + JupyterHub branding
Data pytest Spark, Trino, Iceberg table operations
Notebooks Shell All demo notebooks execute without errors
Dashboards Playwright Superset dashboard rendering
DAGs pytest Airflow DAG parsing and execution
MLflow pytest Experiment tracking, model registry
OPA pytest Trino query policy enforcement
OpenMetadata pytest Catalog ingestion, lineage
Monitoring Shell Prometheus targets, Grafana dashboards

Helm Tests

helm test akko

Runs in-cluster tests defined in helm/akko/charts/*/templates/tests/.

Contributing Guidelines

Branch Strategy

  • main -- production-ready, protected
  • feature/<name> -- feature branches
  • fix/<name> -- bug fix branches

Commit Conventions

  • Use descriptive commit messages
  • Include doc updates in the same commit as code changes
  • Reference issue numbers when applicable

Code Style

  • YAML: 2-space indentation
  • Python: Follow PEP 8, use f-strings
  • Shell: Use shellcheck-compliant scripts
  • All code and configs in English -- comments, variable names, table names

Pull Request Checklist

  • [ ] All tests pass (bash tests/run-all.sh --fast)
  • [ ] Helm lint passes (helm lint helm/akko/)
  • [ ] EN + FR documentation updated
  • [ ] No :latest tags introduced
  • [ ] No secrets or .env files committed
  • [ ] Service count accurate in README

Architecture Principles

  • Sovereignty first -- everything runs offline, on-prem, air-gapped
  • Kubernetes-native -- portable across k3d, k3s, EKS, GKE, AKS, OpenShift
  • Idempotent init -- all init jobs are safe to re-run
  • Two PostgreSQL instances -- never mix infra and business data