Skip to content

Upgrading FCC deployments

This doc covers rolling upgrades between FCC minor versions (1.1.x → 1.2.x), patch upgrades (1.1.0 → 1.1.0.1 → 1.1.1), and chart-only upgrades.

Versioning

FCC uses PEP 440 versioning for the Python package and SemVer-compatible tags for git + container images:

Version Git tag Container tag Significance
1.1.0 v1.1.0 1.1.0, 1.1, latest Minor release — new features, possibly breaking
1.1.0.1 v1.1.0.1 1.1.0.1, 1.1 Patch release — bug fixes only, drop-in
1.1.1 v1.1.1 1.1.1, 1.1, latest Minor release — new features
1.2.0 v1.2.0 1.2.0, 1.2, latest Minor release — new features, possibly breaking

Helm chart version (currently 0.1.0) is decoupled from the app version. Bump it when the chart itself changes (template structure, values schema, etc.) even if the app version stays the same.

Upgrade paths

Patch upgrade (no config changes)

helm repo update
helm upgrade fcc fcc/fcc --reuse-values --version 1.1.0.1

This is a pure rolling upgrade — each Deployment goes through its normal rolling-update strategy (maxSurge: 1, maxUnavailable: 0), so there's no downtime for backend/frontend/streamlit. The jupyter StatefulSet briefly goes offline during the single-pod restart.

Minor upgrade (1.1.x → 1.1.y)

  1. Read the CHANGELOG for the target version — look for BREAKING or Changed entries.
  2. Update values if needed (see "Breaking changes" below).
  3. Backup the jupyter PVC if you have unsaved notebook content: 
    kubectl exec statefulset/fcc-jupyter -- tar cf - /app/notebooks | \
  tar xf - -C ./notebook-backup-$(date +%Y%m%d)
  4. Dry-run the upgrade: 
    helm upgrade --dry-run fcc ./charts/fcc --reuse-values
  5. Apply: 
    helm upgrade fcc ./charts/fcc --reuse-values --wait --timeout 10m
  6. Verify: 
    kubectl get pods -l app.kubernetes.io/instance=fcc
kubectl port-forward svc/fcc-backend 8765:8765 &
curl http://localhost:8765/health

Minor upgrade with config changes

When the new version adds new values you want to set, or renames existing ones, use --values instead of --reuse-values:

helm upgrade fcc ./charts/fcc \
  --values ./values-prod.yaml \
  --set-string global.ai.anthropicApiKey=$ANTHROPIC_API_KEY \
  --set-string jupyter.token=$JUPYTER_TOKEN \
  --wait --timeout 10m

Rollback

If an upgrade goes wrong, roll back to the previous revision:

helm history fcc
# REVISION  UPDATED                   STATUS      CHART     APP VERSION
# 1         2026-04-10 15:00:00       superseded  fcc-0.1.0 1.1.0
# 2         2026-04-11 10:30:00       deployed    fcc-0.1.0 1.1.1  <-- failing
helm rollback fcc 1

Rollbacks execute the same rolling-update strategy in reverse. The jupyter StatefulSet rolls back to the previous container image but keeps its PVC — so notebook content persists across rollbacks.

Breaking changes reference

v1.1.0 → v1.1.0.1

No breaking changes. Drop-in patch that fixes: - Frontend Dockerfile tsc pre-check bypass - Backend image OOM (slim [full] → [protocols,litellm,observability]) - WebSocket /health handler returning proper Response object - Jupyter HOME=/app for non-root startup - CI: docs.yml print-site plugin + publish.yml pandoc install

See CHANGELOG §1.1.0.1.

v1.1.0.1 → v1.1.1

No breaking changes for v1.1.0.1 users. v1.1.1 adds: - Multi-arch image publishing to ghcr.io (pullable images, no local build required) - Helm chart at charts/fcc/ (net-new deployment path) - vLLM provider plugin (opt-in, no impact if VLLM_BASE_URL not set) - Kubernetes + Helm + observability + security + upgrade docs (this doc)

Existing Docker/Compose deployments continue working identically.

v1.1.x → v1.2.x (future)

v1.2.x will add 5 vertical persona packs (insurance, energy, government, expanded medical, expanded finance) with a revised vertical schema (nested R.I.S.C.E.A.R.). The schema change is backward compatible — old vertical YAML files continue to load — but the revised format is preferred for new content.

See v1.2.0 roadmap.

Image tag strategy

Pin to the full version in production for reproducibility:

global:
  imageTag: "1.1.1"   # pinned
  # imageTag: "1.1"   # tracks latest 1.1.x patch (auto-updates)
  # imageTag: "latest" # NOT recommended — can pull v1.2.0 unexpectedly

When you upgrade, change the pinned value:

helm upgrade fcc ./charts/fcc \
  --reuse-values \
  --set global.imageTag=1.1.2

Downtime windows

Component Downtime on upgrade
backend None — rolling update, maxSurge: 1, maxUnavailable: 0
frontend None — same
streamlit None — same
jupyter Brief — StatefulSet replaces the single pod (~30s with readiness probe)

For zero-downtime jupyter, run multiple Helm releases (one per user) or wait for v1.2.0+ which may ship a multi-tenant jupyter option.

Database migrations

FCC is stateless in v1.1.x. There is no database to migrate. The jupyter PVC holds user notebook content; the backend, frontend, and streamlit services hold no persistent state.

See also