Deploying Compass

Build, push, and deploy Compass API and Frontend via Harbor, Gitea, and ArgoCD in the f3iai namespace.

Compass consists of two independently built and deployed components. Both run in the f3iai Kubernetes namespace and are managed by ArgoCD.

Container Images

Build and Push

Builds run on the texas-dell-04 build host, which has Docker and direct access to the Harbor registry.

API

# On your development machine — sync source to build host
rsync -avz --exclude='.git' --exclude='__pycache__' --exclude='.venv' \
  ~/IdeaProjects/federal-frontier-compass/api/ \
  ubuntu@texas-dell-04:~/compass-api/

# On texas-dell-04 — build and push
ssh ubuntu@texas-dell-04
cd ~/compass-api
docker build -t harbor.vitro.lan/ffp/ffo-compass-api:v5.13.79 .
docker push harbor.vitro.lan/ffp/ffo-compass-api:v5.13.79

Frontend

# On your development machine — sync source to build host
rsync -avz --exclude='.git' --exclude='node_modules' --exclude='.next' \
  ~/IdeaProjects/federal-frontier-compass/frontend/ \
  ubuntu@texas-dell-04:~/compass-frontend/

# On texas-dell-04 — build and push
ssh ubuntu@texas-dell-04
cd ~/compass-frontend
docker build -t harbor.vitro.lan/ffp/compass-frontend:v5.1.17 .
docker push harbor.vitro.lan/ffp/compass-frontend:v5.1.17

GitOps Deployment Workflow

Compass is deployed via ArgoCD, which watches a Gitea repository for manifest changes. The deployment workflow is:

Edit code
  → rsync to texas-dell-04
    → docker build & push to Harbor
      → Update image tag in deployment.yaml
        → git push to Gitea
          → ArgoCD detects change and syncs

Step 1: Update the Image Tag

After pushing a new image to Harbor, update the image tag in the Kubernetes deployment manifest:

# deploy/overlays/fmc/compass-api/deployment.yaml
spec:
  containers:
    - name: compass-api
      image: harbor.vitro.lan/ffp/ffo-compass-api:v5.13.79  # ← update tag

# deploy/overlays/fmc/compass-frontend/deployment.yaml
spec:
  containers:
    - name: compass-frontend
      image: harbor.vitro.lan/ffp/compass-frontend:v5.1.17  # ← update tag

Step 2: Push to Gitea

cd ~/IdeaProjects/federal-frontier-f3iai
git add deploy/overlays/fmc/compass-api/deployment.yaml
git commit -m "compass-api: bump to v5.13.79"
git push origin main

ArgoCD watches the main branch of the Gitea repository and will detect the change within its polling interval. Auto-sync and self-heal are enabled, so the new image will be rolled out automatically.

Step 3: Verify

# Check ArgoCD app status
kubectl get application ffp-compass-api -n argocd -o jsonpath='{.status.sync.status}'

# Check pod is running with new image
kubectl get pods -n f3iai -l app=compass-api -o jsonpath='{.items[0].spec.containers[0].image}'

# Hit the health endpoint
curl -s https://compass.vitro.lan/api/health

Important: Never Use kubectl set image

Do not use kubectl set image to update deployments. ArgoCD has auto-sync and self-heal enabled, which means any manual change made via kubectl will be detected as drift and reverted to match the Git state. The image tag in the deployment manifest in Gitea is the single source of truth.

Forcing an ArgoCD Refresh

If ArgoCD has not picked up a change, force a hard refresh by patching the application annotation:

kubectl patch application ffp-compass-api -n argocd \
  --type merge \
  -p '{"metadata":{"annotations":{"argocd.argoproj.io/refresh":"hard"}}}'

This forces ArgoCD to re-read the Git repository and compare against the live state immediately.

Networking

Traefik IngressRoute

Compass is exposed externally via a Traefik IngressRoute at compass.vitro.lan:

• Frontend routes: / (all frontend paths)
• API routes: /api/* (proxied to the API service)

The IngressRoute is defined in the GitOps manifests alongside the deployment resources.

Internal Services

Rollback

To roll back to a previous version:

1. Update the image tag in the deployment manifest to the previous version
2. Commit and push to Gitea
3. ArgoCD will sync and roll back the deployment

Alternatively, use the ArgoCD UI or CLI to sync to a previous Git revision:

argocd app sync ffp-compass-api --revision <previous-commit-sha>