# Stella Ops Docker Compose Profiles

Consolidated Docker Compose configuration for the StellaOps platform. All profiles use immutable image digests from `deploy/releases/*.yaml` and are validated via `docker compose config` in CI.

## Quick Reference

| I want to... | Command |
|--------------|---------|
| Run the full platform | `docker compose -f docker-compose.stella-ops.yml up -d` |
| Add observability | `docker compose -f docker-compose.stella-ops.yml -f docker-compose.telemetry.yml up -d` |
| Run CI/testing infrastructure | `docker compose -f docker-compose.testing.yml --profile ci up -d` |
| Deploy with China compliance | See [China Compliance](#china-compliance-sm2sm3sm4) |
| Deploy with Russia compliance | See [Russia Compliance](#russia-compliance-gost) |
| Deploy with EU compliance | See [EU Compliance](#eu-compliance-eidas) |

---

## File Structure

### Core Stack Files

| File | Purpose |
|------|---------|
| `docker-compose.stella-ops.yml` | **Main stack**: PostgreSQL 18.1, Valkey 9.0.1, RustFS, Rekor v2, all StellaOps services |
| `docker-compose.telemetry.yml` | **Observability**: OpenTelemetry collector, Prometheus, Tempo, Loki |
| `docker-compose.testing.yml` | **CI/Testing**: Test databases, mock services, Gitea for integration tests |
| `docker-compose.dev.yml` | **Minimal dev infrastructure**: PostgreSQL, Valkey, RustFS only |

### Specialized Infrastructure

| File | Purpose |
|------|---------|
| `docker-compose.bsim.yml` | **BSim analysis**: PostgreSQL for Ghidra binary similarity corpus |
| `docker-compose.corpus.yml` | **Function corpus**: PostgreSQL for function behavior database |
| `docker-compose.sealed-ci.yml` | **Air-gapped CI**: Sealed testing environment with authority, signer, attestor |
| `docker-compose.telemetry-offline.yml` | **Offline observability**: Air-gapped Loki, Promtail, OTEL collector, Tempo, Prometheus |

### Regional Compliance Overlays

| File | Purpose | Jurisdiction |
|------|---------|--------------|
| `docker-compose.compliance-china.yml` | SM2/SM3/SM4 ShangMi crypto configuration | China (OSCCA) |
| `docker-compose.compliance-russia.yml` | GOST R 34.10-2012 crypto configuration | Russia (FSB) |
| `docker-compose.compliance-eu.yml` | eIDAS qualified trust services configuration | EU |

### Crypto Provider Overlays

| File | Purpose | Use Case |
|------|---------|----------|
| `docker-compose.crypto-sim.yml` | Universal crypto simulation | Testing without licensed crypto |
| `docker-compose.cryptopro.yml` | CryptoPro CSP (real GOST) | Production Russia deployments |
| `docker-compose.sm-remote.yml` | SM Remote service (real SM2) | Production China deployments |

### Additional Overlays

| File | Purpose | Use Case |
|------|---------|----------|
| `docker-compose.gpu.yaml` | NVIDIA GPU acceleration | Advisory AI inference with GPU |
| `docker-compose.cas.yaml` | Content Addressable Storage | Dedicated CAS with retention policies |
| `docker-compose.tile-proxy.yml` | Rekor tile caching proxy | Air-gapped Sigstore deployments |

### Supporting Files

| Path | Purpose |
|------|---------|
| `env/*.env.example` | Environment variable templates per profile |
| `scripts/backup.sh` | Create deterministic volume snapshots |
| `scripts/reset.sh` | Stop stack and remove volumes (with confirmation) |

---

## Usage Patterns

### Basic Development

```bash
# Copy environment template
cp env/stellaops.env.example .env

# Validate configuration
docker compose -f docker-compose.stella-ops.yml config

# Start the platform
docker compose -f docker-compose.stella-ops.yml up -d

# View logs
docker compose -f docker-compose.stella-ops.yml logs -f scanner-web
```

### With Observability

```bash
# Generate TLS certificates for telemetry
./ops/devops/telemetry/generate_dev_tls.sh

# Start platform with telemetry
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.telemetry.yml up -d
```

### CI/Testing Infrastructure

```bash
# Start CI infrastructure only (different ports to avoid conflicts)
docker compose -f docker-compose.testing.yml --profile ci up -d

# Start mock services for integration testing
docker compose -f docker-compose.testing.yml --profile mock up -d

# Start Gitea for SCM integration tests
docker compose -f docker-compose.testing.yml --profile gitea up -d

# Start everything
docker compose -f docker-compose.testing.yml --profile all up -d
```

**Test Infrastructure Ports:**
| Service | Port | Purpose |
|---------|------|---------|
| postgres-test | 5433 | PostgreSQL 18 for tests |
| valkey-test | 6380 | Valkey for cache/queue tests |
| rustfs-test | 8180 | S3-compatible storage |
| mock-registry | 5001 | Container registry mock |
| gitea | 3000 | Git hosting for SCM tests |

---

## Regional Compliance Deployments

### China Compliance (SM2/SM3/SM4)

**For Testing (simulation):**
```bash
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.compliance-china.yml \
  -f docker-compose.crypto-sim.yml up -d
```

**For Production (real SM crypto):**
```bash
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.compliance-china.yml \
  -f docker-compose.sm-remote.yml up -d
```

**With OSCCA-certified HSM:**
```bash
# Set HSM connection details in environment
export SM_REMOTE_HSM_URL="https://sm-hsm.example.com:8900"
export SM_REMOTE_HSM_API_KEY="your-api-key"

docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.compliance-china.yml \
  -f docker-compose.sm-remote.yml up -d
```

**Algorithms:**
- SM2: Public key cryptography (GM/T 0003-2012)
- SM3: Hash function, 256-bit (GM/T 0004-2012)
- SM4: Block cipher, 128-bit (GM/T 0002-2012)

---

### Russia Compliance (GOST)

**For Testing (simulation):**
```bash
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.compliance-russia.yml \
  -f docker-compose.crypto-sim.yml up -d
```

**For Production (CryptoPro CSP):**
```bash
# CryptoPro requires EULA acceptance
CRYPTOPRO_ACCEPT_EULA=1 docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.compliance-russia.yml \
  -f docker-compose.cryptopro.yml up -d
```

**Requirements for CryptoPro:**
- CryptoPro CSP license files in `opt/cryptopro/downloads/`
- `CRYPTOPRO_ACCEPT_EULA=1` environment variable
- Valid CryptoPro container images

**Algorithms:**
- GOST R 34.10-2012: Digital signature (256/512-bit)
- GOST R 34.11-2012: Hash function (Streebog, 256/512-bit)
- GOST R 34.12-2015: Block cipher (Kuznyechik, Magma)

---

### EU Compliance (eIDAS)

**For Testing (simulation):**
```bash
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.compliance-eu.yml \
  -f docker-compose.crypto-sim.yml up -d
```

**For Production:**
EU eIDAS deployments typically integrate with external Qualified Trust Service Providers (QTSPs) rather than hosting crypto locally. Configure your QTSP integration in the application settings.

```bash
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.compliance-eu.yml up -d
```

**Standards:**
- ETSI TS 119 312 compliant algorithms
- Qualified electronic signatures
- QTSP integration for qualified trust services

---

## Crypto Simulation Details

The `docker-compose.crypto-sim.yml` overlay provides a unified simulation service for all sovereign crypto profiles:

| Algorithm ID | Simulation | Use Case |
|--------------|------------|----------|
| `SM2`, `sm.sim` | HMAC-SHA256 | China testing |
| `GOST12-256`, `GOST12-512` | HMAC-SHA256 | Russia testing |
| `ru.magma.sim`, `ru.kuznyechik.sim` | HMAC-SHA256 | Russia testing |
| `DILITHIUM3`, `FALCON512`, `pq.sim` | HMAC-SHA256 | Post-quantum testing |
| `fips.sim`, `eidas.sim`, `kcmvp.sim` | ECDSA P-256 | FIPS/EU/Korea testing |

**Important:** Simulation is for testing only. Uses deterministic HMAC or static ECDSA keys—not suitable for production or compliance certification.

---

## Configuration Reference

### Infrastructure Services

| Service | Default Port | Purpose |
|---------|--------------|---------|
| PostgreSQL | 5432 | Primary database |
| Valkey | 6379 | Cache, queues, events |
| RustFS | 8080 | S3-compatible artifact storage |
| Rekor v2 | (internal) | Sigstore transparency log |

### Application Services

| Service | Default Port | Purpose |
|---------|--------------|---------|
| Authority | 8440 | OAuth2/OIDC identity provider |
| Signer | 8441 | Cryptographic signing |
| Attestor | 8442 | SLSA attestation |
| Scanner Web | 8444 | SBOM/vulnerability scanning API |
| Concelier | 8445 | Advisory aggregation |
| Notify Web | 8446 | Notification service |
| Issuer Directory | 8447 | CSAF publisher registry |
| Advisory AI Web | 8448 | AI-powered advisory analysis |
| Web UI | 8443 | Angular frontend |

### Environment Variables

Key variables (see `env/*.env.example` for complete list):

```bash
# Database
POSTGRES_USER=stellaops
POSTGRES_PASSWORD=<secret>
POSTGRES_DB=stellaops_platform

# Authority
AUTHORITY_ISSUER=https://authority.example.com

# Scanner
SCANNER_EVENTS_ENABLED=false
SCANNER_OFFLINEKIT_ENABLED=false

# Crypto (for compliance overlays)
STELLAOPS_CRYPTO_PROFILE=default  # or: china, russia, eu
STELLAOPS_CRYPTO_ENABLE_SIM=0     # set to 1 for simulation

# CryptoPro (Russia only)
CRYPTOPRO_ACCEPT_EULA=0  # must be 1 to use CryptoPro

# SM Remote (China only)
SM_SOFT_ALLOWED=1  # software-only SM2
SM_REMOTE_HSM_URL= # optional: OSCCA-certified HSM
```

---

## Networking

All profiles use a shared `stellaops` Docker network. Production deployments can attach a `frontdoor` network for reverse proxy integration:

```bash
# Create external network for load balancer
docker network create stellaops_frontdoor

# Set in environment
export FRONTDOOR_NETWORK=stellaops_frontdoor
```

Only externally-reachable services (Authority, Signer, Attestor, Concelier, Scanner Web, Notify Web, UI) attach to the frontdoor network. Infrastructure services (PostgreSQL, Valkey, RustFS) remain on the private network.

---

## Sigstore Tools

Enable Sigstore CLI tools (rekor-cli, cosign) with the `sigstore` profile:

```bash
docker compose -f docker-compose.stella-ops.yml --profile sigstore up -d
```

---

## GPU Support for Advisory AI

GPU is disabled by default. To enable NVIDIA GPU inference:

```bash
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.gpu.yaml up -d
```

**Requirements:**
- NVIDIA GPU with CUDA support
- nvidia-container-toolkit installed
- Docker configured with nvidia runtime

---

## Content Addressable Storage (CAS)

The CAS overlay provides dedicated RustFS instances with retention policies for different artifact types:

```bash
# Standalone CAS infrastructure
docker compose -f docker-compose.cas.yaml up -d

# Combined with main stack
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.cas.yaml up -d
```

**CAS Services:**
| Service | Port | Purpose |
|---------|------|---------|
| rustfs-cas | 8180 | Runtime facts, signals, replay artifacts |
| rustfs-evidence | 8181 | Merkle roots, hash chains, evidence bundles (immutable) |
| rustfs-attestation | 8182 | DSSE envelopes, in-toto attestations (immutable) |

**Retention Policies (configurable via `env/cas.env.example`):**
- Vulnerability DB: 7 days
- SBOM artifacts: 365 days
- Scan results: 90 days
- Evidence bundles: Indefinite (immutable)
- Attestations: Indefinite (immutable)

---

## Tile Proxy (Air-Gapped Sigstore)

For air-gapped deployments, the tile-proxy caches Rekor transparency log tiles locally from public Sigstore:

```bash
docker compose -f docker-compose.stella-ops.yml \
  -f docker-compose.tile-proxy.yml up -d
```

**Tile Proxy vs Rekor v2:**
- Use `--profile sigstore` when running your own Rekor transparency log locally
- Use `docker-compose.tile-proxy.yml` when caching tiles from public Sigstore (rekor.sigstore.dev)

**Configuration:**
| Variable | Default | Purpose |
|----------|---------|---------|
| `REKOR_SERVER_URL` | `https://rekor.sigstore.dev` | Upstream Rekor to proxy |
| `TILE_PROXY_SYNC_ENABLED` | `true` | Enable periodic tile sync |
| `TILE_PROXY_SYNC_SCHEDULE` | `0 */6 * * *` | Sync every 6 hours |
| `TILE_PROXY_CACHE_MAX_SIZE_GB` | `10` | Local cache size limit |

The proxy syncs tiles on schedule and serves them to internal services for offline verification.

---

## Maintenance

### Backup

```bash
./scripts/backup.sh  # Creates timestamped tar.gz of volumes
```

### Reset

```bash
./scripts/reset.sh  # Stops stack, removes volumes (requires confirmation)
```

### Validate Configuration

```bash
docker compose -f docker-compose.stella-ops.yml config
```

### Update to New Release

1. Import new manifest to `deploy/releases/`
2. Update image digests in compose files
3. Run `docker compose config` to validate
4. Run `deploy/tools/validate-profiles.sh` for audit

---

## Troubleshooting

### Port Conflicts

Override ports in your `.env` file:
```bash
POSTGRES_PORT=5433
VALKEY_PORT=6380
SCANNER_WEB_PORT=8544
```

### Service Dependencies

Services declare `depends_on` with health checks. If a service fails to start, check its dependencies:
```bash
docker compose -f docker-compose.stella-ops.yml ps
docker compose -f docker-compose.stella-ops.yml logs postgres
docker compose -f docker-compose.stella-ops.yml logs valkey
```

### Crypto Provider Issues

For crypto simulation issues:
```bash
# Check sim-crypto service
docker compose logs sim-crypto
curl http://localhost:18090/keys
```

For CryptoPro issues:
```bash
# Verify EULA acceptance
echo $CRYPTOPRO_ACCEPT_EULA  # must be 1

# Check CryptoPro service
docker compose logs cryptopro-csp
```

---

## Related Documentation

- [Deployment Upgrade Runbook](../../docs/operations/devops/runbooks/deployment-upgrade.md)
- [Local CI Guide](../../docs/technical/testing/LOCAL_CI_GUIDE.md)
- [Crypto Profile Configuration](../../docs/security/crypto-profile-configuration.md)
- [Regional Deployments](../../docs/operations/regional-deployments.md)