Container image (Phase 1.5.c)

Ghillie provides a container image for Kubernetes deployments. The image runs a Falcon Asynchronous Server Gateway Interface (ASGI) application served by Granian, with health endpoints for Kubernetes probes.

Build the image locally using the provided Makefile target:

make docker-build

This produces an image tagged ghillie:local using a multi-stage build. The build stage creates a wheel from the source, and the runtime stage installs it into a minimal Python 3.14 slim image with a non-root user.

Alternatively, build directly with Docker:

docker build -t ghillie:local .

Run the container locally to verify the build:

docker run --rm -p 8080:8080 ghillie:local

The container starts the Granian server and logs a startup message. Verify the health endpoints:

curl http://localhost:8080/health
# Returns: {"status": "ok"}

curl http://localhost:8080/ready
# Returns: {"status": "ready"}

The runtime reads configuration from environment variables:

Additional environment variables for database and cache connectivity should be injected via Kubernetes Secrets when deploying with the Helm chart.

The runtime exposes two health endpoints for Kubernetes probes:

• /health: Liveness probe endpoint. Returns {"status": "ok"} when the process is alive.
• /ready: Readiness probe endpoint. Returns {"status": "ready"} when the service is ready to accept traffic.

Both endpoints return HTTP 200 with JSON content type.

The runtime health endpoints are documented in the OpenAPI specification:

• specs/openapi.yml

For Kubernetes deployment, use the Ghillie Helm chart in charts/ghillie/. Configure liveness and readiness probes in the chart values:

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 15

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

For local k3d previews, import the image into the cluster:

k3d image import ghillie:local -c <cluster-name>