Deployment Guide

Deployment Environments

---

GitLab Pages (Production)

Production deploys to GitLab Pages when manually triggered on main branch.

How It Works

1. Merge to main branch
2. Pipeline runs build jobs
3. Click "Deploy" on pages job (manual)
4. Site deploys to https://openstandardagents.org

The Pages Job

pages:
  stage: deploy
  needs:
    - build:website
  script:
    - cp -r website-build public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      when: manual

---

Review Apps (Local K8s)

Review apps deploy to local OrbStack Kubernetes cluster for preview.

Prerequisites

1. OrbStack with Kubernetes enabled
2. nginx-ingress controller installed
3. KUBECONFIG_LOCAL CI variable set

Setup

# 1. Install OrbStack (https://orbstack.dev)
# 2. Enable Kubernetes in OrbStack settings

# 3. Get kubeconfig
kubectl config view --raw | base64 | pbcopy

# 4. Add to GitLab CI/CD Variables:
#    Key: KUBECONFIG_LOCAL
#    Value: (paste from clipboard)
#    Protected: Yes
#    Masked: Yes

Review App URLs

• Pattern: mr-{MR_ID}.openstandardagents.orb.local
• Example: http://mr-264.openstandardagents.orb.local

Cleanup

Review apps auto-stop after 1 week. Manual cleanup:

1. GitLab UI: Settings CI/CD Environments
2. Or run review:stop job manually

---

Docker Build

# Build image
docker build -t openstandardagents.org:latest .

# Run locally
docker run -p 3000:3000 openstandardagents.org:latest

Multi-stage Dockerfile

The project uses a multi-stage build:

1. deps - Install dependencies
2. builder - Build Next.js site
3. runner - Production runtime (Alpine)

---

Auto-Sync System

The website automatically syncs content from multiple sources.

Data Sources

Sync Job Triggers

1. Scheduled - Every 6 hours via pipeline schedule
2. Push to main/release - On branch updates
3. Manual - Run sync:auto job manually

What Gets Synced

• website/public/examples.json - 100+ OSSA examples
• website/lib/versions.json - Version metadata
• website/lib/release-highlights.json - Release notes
• website/content/spec/ - OSSA specification schema

Sync Flow

  npm registry     @bluefly/ossa package
  GitLab API       Wiki content
  GitHub repos     Example agents

         
         

   sync:auto      CI job runs fetch scripts
   CI Job        

          Changes detected?
         

  Creates MR      Auto-merge enabled
  with changes    Labels: workflow::auto-merge

         
         

  Pipeline runs   Build + tests
  MR auto-merges 

---

Manual Deployment

Deploy from Local

# 1. Build locally
cd website
npm run build

# 2. Export static site
npm run export  # if configured

# 3. Copy to server
rsync -avz out/ user@server:/var/www/ossa/

Force Sync

# Run all sync scripts
cd website
npm run fetch-spec
npm run fetch-examples
npm run fetch-versions
npm run fetch-highlights
npm run sync-version
npm run fix-versions

# Commit and push
git add .
git commit -m "chore: manual sync"
git push

---

Environment Variables

Build Time

CI/CD Variables

---

Monitoring

Health Checks

• GitLab Pages status: https://status.gitlab.com
• Pipeline status: Check CI/CD Pipelines

Logs

1. Build logs: CI/CD Jobs Select job
2. Pages logs: Deploy Pages View logs

Performance

• Lighthouse CI runs on every MR
• Target scores: Performance > 90, Accessibility > 90