Upgrade POC Factory from v1.1.0 to v1.1.1#

Update the backend, frontend, and GitHub MCP proxy as one release set. The v1.1.1 tag introduces no database schema changes or mandatory environment or secret changes; keep your existing settings, keys, credentials, and persistent data.

Prerequisites#

Prepare a recoverable baseline before changing the images.

  1. Confirm pull access to all three nvcr.io/nvidia images tagged 1.1.1, or the corresponding approved mirror digests.

  2. Record the running v1.1.0 image references, Compose project or Helm release name, and environment configuration revision.

  3. Wait for active work to finish or plan an approved maintenance window. Durable job records do not guarantee that an in-flight backend process continues through a restart.

  4. Back up PostgreSQL, generated POCs, NAT job state, and any fine-tuning data at a coordinated point in time. Protect the corresponding secrets and confirm the restore procedure.

Do not regenerate ENCRYPTION_KEY or overwrite .env from a fresh template. Changing the encryption key can make saved credentials unreadable.

Upgrade Docker Compose#

Run from the existing deployment directory so the Compose project name, host directories, and named volumes remain the same.

  1. Download the v1.1.1 Compose deployment bundle and compare it with your current deployment files. Keep environment-owned changes and the existing .env; replace deployment files only after reviewing the differences.

  2. Update these existing .env values:

    NIM_NGC_ORG=nvidia
VERSION=1.1.1

    Use the approved mirror namespace if applicable. Remove or update POC_FACTORY_MCP_VERSION, GITHUB_MCP_PROXY_VERSION, and FRONTEND_VERSION if they pin older tags; those values override VERSION. Also check exported shell variables, which can override Compose interpolation from .env.

  3. Authenticate, inspect the resolved image set, then pull and recreate the services:

    docker login nvcr.io --username '$oauthtoken'
docker compose --profile mcp config --images
docker compose --profile mcp pull
docker compose --profile mcp up -d
docker compose --profile mcp ps
curl -fsS http://localhost:8000/health

    For an existing deployment that uses Phoenix, use --profile full consistently instead of --profile mcp.

  4. Confirm all three application image references are 1.1.1. PostgreSQL and Phoenix use separate image versions.

An image refresh does not require deleting volumes or resetting the database. Do not use docker compose down --volumes during this upgrade.

Upgrade Kubernetes or GitOps#

Keep the namespace, release name, Secret references, database, and PVCs aligned with the running deployment.

  1. Download the v1.1.1 Helm chart, extract it, and compare the chart and values with the current release. Keep your environment-owned values file.

  2. Update the image organization and tag for pocFactory.image, frontend.image, and githubMcpProxy.image together. Public catalog images use organization nvidia and tag 1.1.1.

  3. Render and inspect the upgrade before applying it:

    helm lint ./poc-factory -f environment-values.yaml
helm template poc-factory ./poc-factory -n poc-factory -f environment-values.yaml > /tmp/poc-factory-upgrade.yaml

  4. Verify image references, existing Secret names, ingress, PostgreSQL connection, PVCs, and validation flags. Retain authentication, TLS, and the stable encryption key.

  5. Apply the upgrade through the deployment’s usual controller. For a direct Helm deployment:

    helm upgrade poc-factory ./poc-factory -n poc-factory -f environment-values.yaml --wait --timeout 10m
kubectl get pods,svc,ingress,pvc -n poc-factory

    For GitOps, commit the chart and image updates to the deployment repository and synchronize through the controller; do not apply a parallel Helm change.

Verify the Upgrade#

Run these checks after the rollout, including a real user workflow.

  1. Verify running tags or digests and healthy containers or pods. Check the backend /health response reports version 1.1.1 with healthy database and state-manager checks.

  2. Open the frontend and complete sign-in when authentication is enabled.

  3. Confirm an existing POC remains visible and downloadable and that saved Settings credentials still work.

  4. Validate inference and Cursor settings, then generate and download a small POC. Record which candidate gates passed or were skipped.

  5. Restart or roll the backend after the smoke workflow and confirm inventory, archives, and saved settings remain usable.

A healthy rollout alone does not validate authenticated generation or fine-tuning. Record the user checks that you actually performed.

Roll Back#

Use the retained image and configuration baseline if the new release fails verification.

  1. Stop new work and collect the failing job ID and logs without exposing secrets.

  2. Restore the previous Compose image settings and reviewed deployment files, or revert the GitOps commit. Direct Helm deployments can restore the recorded revision with helm rollback.

  3. Roll out the previous three-image release set and verify health, sign-in, existing archive downloads, and saved credentials.

  4. If data recovery is necessary, restore the coordinated database and storage backup with its original encryption key in an isolated recovery procedure. Do not mix a restored database with unrelated artifact snapshots.

Next Steps#

Record the verified image digests, configuration revision, backup point, and user checks in the deployment handoff. Use Troubleshooting for remaining failures and Operate and restore for routine operations.