# StellaOps Deployment Version Matrix

> **Last Updated:** 2025-12-04
> **Purpose:** Single source of truth for service versions across deployment environments
> **Unblocks:** COMPOSE-44-001, 44-001, 44-002, 44-003, 45-001, 45-002, 45-003 (7 tasks)

## Quick Reference

| Environment | Core Version | Status |
|-------------|-------------|--------|
| **Development** | `2025.10.0-edge` | Active |
| **Staging** | `2025.09.2` | Stable |
| **Production** | `2025.09.2` | Stable |
| **Air-Gap** | `2025.09.2-airgap` | Certified |

---

## Service Version Matrix

### Core Services

| Service | Dev | Staging | Prod | Air-Gap | Notes |
|---------|-----|---------|------|---------|-------|
| Authority | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | OAuth 2.1 / mTLS |
| Signer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | ECDSA/RSA/EdDSA |
| Attestor | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | in-toto/DSSE |
| Concelier | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Advisory ingestion |
| Scanner | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | SBOM/Vuln scanning |
| Excititor | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | VEX export |
| Policy | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | OPA/Rego engine |
| Scheduler | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Job scheduling |
| Notify | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Notifications |

### Platform Services

| Service | Dev | Staging | Prod | Air-Gap | Notes |
|---------|-----|---------|------|---------|-------|
| Orchestrator Web | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | API Gateway |
| Orchestrator Worker | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Background jobs |
| Graph API | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Graph queries |
| Graph Indexer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Graph ingest |
| Timeline Indexer | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Event timeline |
| Findings Ledger | `2025.10.0-edge` | `2025.09.2` | `2025.09.2` | `2025.09.2-airgap` | Finding storage |

### Infrastructure Dependencies

| Component | Version | Digest | Notes |
|-----------|---------|--------|-------|
| MongoDB | `7.0` | `sha256:c258b26dbb7774f97f52aff52231ca5f228273a84329c5f5e451c3739457db49` | Primary database |
| PostgreSQL | `16-alpine` | N/A | Scheduler/metadata |
| MinIO | `RELEASE.2024-01-01` | `sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e` | Object storage |
| NATS | `2.10` | `sha256:c82559e4476289481a8a5196e675ebfe67eea81d95e5161e3e78eccfe766608e` | Message queue |
| RustFS | `2025.10.0-edge` | N/A | Content-addressed storage |

---

## Container Image Registry

### Primary Registry

```
registry.stella-ops.org/stellaops/<service>:<version>
```

### Image Naming Convention

| Pattern | Example | Use Case |
|---------|---------|----------|
| `<service>:<version>` | `authority:2025.09.2` | Tagged releases |
| `<service>:<version>-<variant>` | `authority:2025.09.2-airgap` | Environment variants |
| `<service>:edge` | `authority:edge` | Latest dev build |
| `<service>@sha256:<digest>` | `authority@sha256:abc123...` | Immutable reference |

### Air-Gap Bundle Images

Air-gap deployments use pre-bundled images with all dependencies:

```
registry.stella-ops.org/stellaops/airgap-bundle:2025.09.2
```

Bundle contents:
- All core services at matching version
- Infrastructure containers (Mongo, MinIO, NATS)
- CLI tools and migration utilities
- Offline kit documentation

---

## Version Promotion Workflow

### Stages

```
Dev (edge) → Staging → Production → Air-Gap (certified)
```

### Promotion Criteria

| Stage | Criteria |
|-------|----------|
| Dev → Staging | All unit tests pass, integration tests pass |
| Staging → Prod | E2E tests pass, security scan clean, performance benchmarks pass |
| Prod → Air-Gap | Offline validation complete, bundle integrity verified, documentation updated |

### Promotion Commands

```bash
# Promote dev to staging
./scripts/promote.sh --from dev --to staging --version 2025.10.0

# Promote staging to production
./scripts/promote.sh --from staging --to prod --version 2025.10.0

# Create air-gap certified bundle
./scripts/create-airgap-bundle.sh --version 2025.09.2
```

---

## Helm Chart Values

### Development (`values-dev.yaml`)

```yaml
global:
  imageTag: "2025.10.0-edge"
  imagePullPolicy: Always
  environment: development

services:
  authority:
    replicaCount: 1
    resources:
      requests:
        memory: "256Mi"
        cpu: "100m"
```

### Production (`values-prod.yaml`)

```yaml
global:
  imageTag: "2025.09.2"
  imagePullPolicy: IfNotPresent
  environment: production

services:
  authority:
    replicaCount: 3
    resources:
      requests:
        memory: "512Mi"
        cpu: "250m"
```

### Air-Gap (`values-airgap.yaml`)

```yaml
global:
  imageTag: "2025.09.2-airgap"
  imagePullPolicy: Never  # Images pre-loaded
  environment: airgap
  offlineMode: true

airgap:
  enabled: true
  bundleVersion: "2025.09.2"
  stalenessThresholdSeconds: 604800  # 7 days
```

---

## Docker Compose Reference

### Quick Start (Development)

```yaml
# docker-compose.dev.yaml
version: "3.8"
services:
  authority:
    image: registry.stella-ops.org/stellaops/authority:2025.10.0-edge

  concelier:
    image: registry.stella-ops.org/stellaops/concelier:2025.10.0-edge

  scanner:
    image: registry.stella-ops.org/stellaops/scanner:2025.10.0-edge
```

### Production

```yaml
# docker-compose.prod.yaml
version: "3.8"
services:
  authority:
    image: registry.stella-ops.org/stellaops/authority@sha256:...
    deploy:
      replicas: 3

  concelier:
    image: registry.stella-ops.org/stellaops/concelier@sha256:...
    deploy:
      replicas: 2
```

---

## Service Dependencies

### Startup Order

```
1. Infrastructure (MongoDB, NATS, MinIO)
   ↓
2. Core Auth (Authority, Signer)
   ↓
3. Data Services (Concelier, Excititor)
   ↓
4. Compute Services (Scanner, Policy, Scheduler)
   ↓
5. Platform Services (Orchestrator, Graph, Timeline)
   ↓
6. UI/CLI
```

### Health Check Endpoints

| Service | Health Endpoint | Ready Endpoint |
|---------|-----------------|----------------|
| All | `/health` | `/ready` |
| Authority | `/health` | `/ready` (includes JWKS) |
| Scanner | `/health` | `/ready` (includes analyzer check) |

---

## Breaking Changes Log

### 2025.10.0 (Upcoming)

- **Authority:** New OAuth 2.1 endpoints (backward compatible)
- **Scanner:** Analyzer plugin format v2 (migration required)
- **Concelier:** LNM API v2 (v1 deprecated, removed in 2025.11.0)

### 2025.09.2 (Current Stable)

- **All:** Initial GA release
- **Air-Gap:** First certified offline bundle

---

## Rollback Procedure

### Helm Rollback

```bash
# List releases
helm history stellaops -n stellaops

# Rollback to previous
helm rollback stellaops 1 -n stellaops
```

### Compose Rollback

```bash
# Stop current
docker-compose down

# Edit .env to previous version
# VERSION=2025.09.1

# Start previous
docker-compose up -d
```

---

## Related Documents

- [Helm Chart Documentation](../deploy/helm/stellaops/README.md)
- [Compose Quickstart](../deploy/compose/README.md)
- [Offline Kit Guide](./24_OFFLINE_KIT.md)
- [Air-Gap Provenance](../modules/findings-ledger/airgap-provenance.md)
- [Staleness Schema](../schemas/ledger-airgap-staleness.schema.json)

---

## Changelog

| Date | Change | Author |
|------|--------|--------|
| 2025-12-04 | Initial version matrix created | Claude |
| 2025-12-04 | Added air-gap certification workflow | Claude |