Skip to content

FCC Deployment Guide

This guide walks you through the two supported deployment paths for the FCC Agent Team Framework: Docker Compose (for single-host environments) and the official Helm chart (for Kubernetes clusters). Both are shipped and tested by the project — this is the path of least surprise.

The artefacts referenced in this guide:

  • docker-compose.yml — local + staging topology (4 services)
  • docker-compose.prod.yml — production overlay
  • charts/fcc/ — Helm chart (Chart.yaml version 0.2.10, appVersion 1.3.9+)
  • charts/fcc/values.yaml — default values
  • charts/fcc/values-prod.yaml — production overrides
  • docker/Dockerfile.{backend,frontend,streamlit,jupyter} — 4 production images

Path A — Docker Compose

Docker Compose is the right answer for staging, demos, internal previews, and teams of fewer than 20 users sharing one environment.

Prerequisites

  • Docker 24+ with Compose v2
  • 4 GiB RAM, 2 vCPU free on the host
  • Either ANTHROPIC_API_KEY or OPENAI_API_KEY (or the stack stays in mock mode)

Bring-up

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext

# 1. Author a .env (never commit)
cp .env.example .env
editor .env   # set ANTHROPIC_API_KEY / OPENAI_API_KEY

# 2. Build all four images
make docker-build

# 3. Bring the stack up
make docker-up

# 4. Inspect health
curl -sf http://localhost:8765/health
open http://localhost:8080/   # React frontend
open http://localhost:8501/   # Streamlit app
open http://localhost:8888/   # JupyterLab

Production Overlay

For internal staging deployments, layer the production overlay on top:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

The overlay pins image tags, disables development-only volume mounts, switches JupyterLab to token-required mode, and enables restart-policy always.

Tear-down

make docker-down   # stops + removes containers; keeps volumes

Path B — Helm on Kubernetes

The Helm chart is the supported production deployment path. It ships 12+ Kubernetes resources and is under continuous CI via the k8s-smoke job (first green in v1.2.1, continuously green since).

Prerequisites

  • Kubernetes 1.25+ (the chart pins kubeVersion: ">=1.25.0")
  • Helm 3.12+
  • An ingress controller (nginx, Traefik, or AWS Load Balancer Controller)
  • Cert-manager or an alternative TLS provisioner
  • A StorageClass that supports ReadWriteOnce for the JupyterLab PVC

Install

# 1. Add the namespace
kubectl create namespace fcc

# 2. Author a secret
kubectl -n fcc create secret generic fcc-secrets \
    --from-literal=ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
    --from-literal=OPENAI_API_KEY=$OPENAI_API_KEY

# 3. Install the chart
helm install fcc ./charts/fcc \
    --namespace fcc \
    --values ./charts/fcc/values.yaml \
    --values ./charts/fcc/values-prod.yaml

# 4. Verify
kubectl -n fcc get pods
kubectl -n fcc port-forward svc/fcc-backend 8765:8765 &
curl -sf http://localhost:8765/health

Expected pod inventory after a clean install:

Workload Kind Replicas
fcc-backend Deployment 2
fcc-frontend Deployment 2
fcc-streamlit Deployment 1
fcc-jupyter StatefulSet 1

Tuning values.yaml

The most common overrides:

backend:
  replicaCount: 3
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 2
      memory: 4Gi

frontend:
  ingress:
    enabled: true
    className: nginx
    host: fcc.example.com
    tls:
      enabled: true
      secretName: fcc-tls

observability:
  otel:
    enabled: true
    endpoint: http://otel-collector.observability:4317

Upgrading

helm upgrade fcc ./charts/fcc \
    --namespace fcc \
    --values values-prod.yaml \
    --atomic \
    --timeout 10m

The --atomic flag auto-rolls-back on failure. See Upgrade Guide for the full version-bump protocol.

Rollback

helm rollback fcc <previous-revision> --namespace fcc

Path C — Manual docker run

Not recommended. Use only when neither Compose nor Kubernetes is available. The command shape is on the deployment module docs.

Environment Variable Reference

Variable Meaning Default
FCC_LOG_LEVEL Root logger level INFO
FCC_DEFAULT_PROVIDER AI provider mock
ANTHROPIC_API_KEY Anthropic key (unset)
OPENAI_API_KEY OpenAI key (unset)
AZURE_OPENAI_API_KEY Azure OpenAI key (unset)
OLLAMA_BASE_URL Local Ollama endpoint (unset)
LITELLM_DEFAULT_MODEL LiteLLM router target (unset)
FCC_EVENT_BUS_BUFFER_SIZE Event ring buffer 1024
FCC_OTEL_ENDPOINT OTel collector gRPC (unset)

The provider matrix follows conservative auto-detection: each provider activates only when its hint environment variable is present. See the AI provider matrix in the root CLAUDE.md.

First-Day Checklist

  • curl /health returns 200 OK on the backend
  • Frontend loads in a browser and shows the persona catalogue
  • One Streamlit app renders without error
  • JupyterLab is accessible with a token (never token-less in production)
  • Secrets are sourced from a Secret resource, not image layers
  • The ingress terminates TLS; no plain HTTP externally
  • fcc admin health (see Incident Response) returns green
  • OpenTelemetry traces appear in your collector