Quickstart: Hello Solution

By the end of this tutorial you will have a FastAPI service running in a local Kubernetes cluster, packaged as a Helm chart that wraps the platform’s em-service base chart, and reachable by curl. Total time: 30 minutes or less. If it takes longer, that’s a guide bug — please report via the 👎 thumbs at the bottom of this page.

This tutorial keeps every command and config snippet inline. Its one external dependency is the platform’s em-service base chart, pulled from Emergence’s private container registry during install — registry access is granted to the Emergence team and Solution/Agent design partners (you authenticate with helm registry login in the install step).

Prerequisites

Install these tools. Versions are floors, not pins — newer is fine.

Tool	Version	Purpose
Docker	24+	Container runtime for Kind
Kind	0.20+	Local Kubernetes cluster
kubectl	1.28+	Kubernetes CLI
Helm	3.13+	Package manager for Kubernetes
uv	0.4+	Python project manager

macOS
Linux

brew install docker kind kubectl helm uv

# Docker — follow distro-specific instructions at https://docs.docker.com/engine/install/

# Kind
curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-amd64
chmod +x ./kind && sudo mv ./kind /usr/local/bin/kind

# kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl && sudo mv kubectl /usr/local/bin/

# Helm
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

What you’ll build

A solution called hello-solution with one component (api) that exposes:

GET /healthz → {"status":"ok"} for k8s probes
GET /echo?msg=... → echoes the message back

The image is built locally and loaded into Kind (no registry needed). The Helm chart wraps em-service v0.0.15 with alias: api, so you’ll see how multi-component solutions extend (just add another alias).

Steps

Create the project layout

Pick a working directory and scaffold these files:

hello-solution/
├── packages/api/
│   ├── pyproject.toml
│   └── src/api/
│       └── main.py
├── Dockerfile
└── charts/hello-solution/
    ├── Chart.yaml
    └── values.yaml

mkdir -p hello-solution/packages/api/src/api hello-solution/charts/hello-solution
cd hello-solution

Write the FastAPI app

from fastapi import FastAPI

app = FastAPI(title="hello-solution")

@app.get("/healthz")
async def healthz() -> dict[str, str]:
    return {"status": "ok"}

@app.get("/echo")
async def echo(msg: str = "hi") -> dict[str, str]:
    return {"echo": msg}

[project]
name = "hello-solution-api"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
  "fastapi>=0.110",
  "uvicorn[standard]>=0.30",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/api"]

Write the Dockerfile

A multi-stage build keeps the runtime image small.

Dockerfile

FROM python:3.12-slim AS build
WORKDIR /app
RUN pip install --no-cache-dir uv
COPY packages/api/pyproject.toml packages/api/pyproject.toml
COPY packages/api/src packages/api/src
RUN uv pip install --system --no-cache-dir ./packages/api

FROM python:3.12-slim
COPY --from=build /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=build /usr/local/bin/uvicorn /usr/local/bin/uvicorn
EXPOSE 8000
CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "8000"]

Write the Helm chart

The chart declares one em-service subchart, aliased as api. The platform’s em-service (v0.0.15) handles Deployment, Service, probes, env vars — you only configure your image and ports. To add a worker later, you’d add another em-service entry with alias: worker and configure it under that alias key in values.yaml. See em-service Chart for the full values reference.

apiVersion: v2
name: hello-solution
description: A minimal CRAFT solution
type: application
version: 0.1.0
appVersion: "0.1.0"
dependencies:
  - name: em-service
    alias: api
    version: 0.0.15        # latest tag published to the OCI registry
    repository: oci://ghcr.io/emergenceai/em-charts

Why 0.0.15 and not the latest source version? The em-charts source
Chart.yaml is on 0.0.16 (and an unrelated 0.1.0 ships for
em-charts-internal/em-service-internal), but the OCI tag
ghcr.io/emergenceai/em-charts/em-service:0.0.15 is the most recent
version actually published to the registry — 0.0.16 returns “not found”
on helm pull. em-talk2data’s own Chart.yaml pins 0.0.15 for the
same reason. When em-charts publishes a newer tag, bump here.

api:
  # em-service's fullname template defaults to the release name, which would
  # name every component "hello-solution" — collide if you add another alias.
  # Set fullnameOverride per component so resources are named "<solution>-<component>"
  # (this is what em-runtime itself does for governance/assets/utils).
  fullnameOverride: hello-solution-api
  image:
    repository: hello-solution-api
    tag: dev
    pullPolicy: IfNotPresent
  service:
    type: ClusterIP
    port: 8000
  env:
    LOG_LEVEL: "INFO"
  readinessProbe:
    httpGet:
      path: /healthz
      port: 8000
    initialDelaySeconds: 2
  livenessProbe:
    httpGet:
      path: /healthz
      port: 8000
    initialDelaySeconds: 5

Create a Kind cluster and load your image

# Create cluster
kind create cluster --name hello-solution

# Build and load image
docker build -t hello-solution-api:dev .
kind load docker-image hello-solution-api:dev --name hello-solution

kind load docker-image makes your local image available inside the cluster without a registry.

Install the chart

# Authenticate to the private em-charts registry first (team / design-partner access)
helm registry login ghcr.io
helm dependency update ./charts/hello-solution
helm upgrade --install hello-solution ./charts/hello-solution \
  --namespace em-hello-solution --create-namespace \
  --wait --timeout 5m

First install pulls em-service from ghcr.io/emergenceai/em-charts, a private registry — helm registry login ghcr.io authenticates you (access is granted to the Emergence team and Solution/Agent design partners).

Smoke-test it

kubectl port-forward -n em-hello-solution svc/hello-solution-api 8000:8000 &

curl -s "http://localhost:8000/healthz" | jq .
# {"status":"ok"}

curl -s "http://localhost:8000/echo?msg=ship%20it" | jq .
# {"echo":"ship it"}

If both calls succeed, you have shipped your first CRAFT solution.

Tear down

kill %1 2>/dev/null  # stop port-forward
helm uninstall hello-solution -n em-hello-solution
kubectl delete namespace em-hello-solution
kind delete cluster --name hello-solution

What you just did

You wrapped a 25-line FastAPI app in a Helm chart that depends on the platform’s em-service base chart, deployed it to a namespace named em-<solution> (the platform convention), and reached it via port-forward. You did not configure auth, secrets, storage, or LLMs yet — those are the next how-tos:

Register a solution

Make this naming + namespace pattern systematic.

Authenticate users

Protect /echo with JWT validation.

Manage secrets

Wire a secret-backed env var into your chart.

Local development

Loop faster with docker-compose + hot reload.

​Quickstart: Hello Solution

​Prerequisites

​What you’ll build

​Steps

​What you just did

Register a solution

Authenticate users

Manage secrets

Local development

Quickstart: Hello Solution

Prerequisites

What you’ll build

Steps

What you just did