# Local Integration Services

This guide covers the third-party services available for local integration testing with Stella Ops.

## Architecture Overview

```
                          stellaops network
  +------------------------------------------------------------------+
  |                                                                    |
  |  STELLA OPS CORE                  INTEGRATION SERVICES             |
  |  (docker-compose.stella-ops.yml)  (docker-compose.integrations.yml)|
  |                                                                    |
  |  router-gateway ─────────> gitea        (SCM)       127.1.2.1:3000 |
  |  concelier      ─────────> jenkins      (CI/CD)     127.1.2.2:8080 |
  |  integrations   ─────────> nexus        (Registry)  127.1.2.3:8081 |
  |  scanner        ─────────> vault        (Secrets)   127.1.2.4:8200 |
  |  evidence-locker ────────> docker-reg   (Registry)  127.1.2.5:5000 |
  |  airgap-controller ──────> minio        (S3)        127.1.2.6:9000 |
  |                            gitlab [heavy](All-in-1) 127.1.2.7:8929 |
  |                                                                    |
  |  MOCK FIXTURES (docker-compose.integration-fixtures.yml)           |
  |  harbor-fixture   (Registry mock)   127.1.1.6:80                   |
  |  github-app-fixture (SCM mock)      127.1.1.7:80                   |
  |  advisory-fixture (Advisory mock)   127.1.1.8:80                   |
  +------------------------------------------------------------------+
```

## Quick Start

### Prerequisites
- Docker Desktop with 8 GB+ RAM allocated
- The main Stella Ops stack running (`docker-compose.stella-ops.yml`)
- Hosts file entries (see below)

### 1. Add hosts file entries

Add to `C:\Windows\System32\drivers\etc\hosts`:

```
127.1.2.1  gitea.stella-ops.local
127.1.2.2  jenkins.stella-ops.local
127.1.2.3  nexus.stella-ops.local
127.1.2.4  vault.stella-ops.local
127.1.2.5  registry.stella-ops.local
127.1.2.6  minio.stella-ops.local
127.1.2.7  gitlab.stella-ops.local
```

### 2. Start services

```bash
cd devops/compose

# Start all lightweight services (recommended)
docker compose -f docker-compose.integrations.yml up -d

# Or start specific services only
docker compose -f docker-compose.integrations.yml up -d gitea vault jenkins

# Start WITH mock fixtures (for full integration testing)
docker compose \
  -f docker-compose.integrations.yml \
  -f docker-compose.integration-fixtures.yml \
  up -d

# Start GitLab CE (heavy, 4 GB+ RAM, ~3 min startup)
docker compose -f docker-compose.integrations.yml --profile heavy up -d gitlab
```

### 3. Verify services

```bash
# Quick health check for all services
docker compose -f docker-compose.integrations.yml ps
```

---

## Service Reference

### Gitea (SCM)

| Property | Value |
|----------|-------|
| URL | http://gitea.stella-ops.local:3000 |
| API | http://gitea.stella-ops.local:3000/api/v1 |
| SSH | gitea.stella-ops.local:2222 |
| First-run | Create admin account via web UI |
| Swagger | http://gitea.stella-ops.local:3000/api/swagger |
| Integration type | SCM (Gitea provider) |
| Docker DNS | `gitea.stella-ops.local` |

**Stella Ops integration config:**
- Endpoint: `http://gitea.stella-ops.local:3000`
- AuthRef: `authref://vault/gitea#api-token`
- Organization: *(your Gitea org name)*

**Create an API token:**
1. Log in to Gitea
2. Settings > Applications > Generate Token
3. Store in Vault at `secret/gitea` with key `api-token`

---

### Jenkins (CI/CD)

| Property | Value |
|----------|-------|
| URL | http://jenkins.stella-ops.local:8080 |
| API | http://jenkins.stella-ops.local:8080/api/json |
| Admin | Setup wizard disabled; create user via script console |
| Agent port | 127.1.2.2:50000 |
| Integration type | CI/CD (Jenkins provider) |
| Docker DNS | `jenkins.stella-ops.local` |

**Stella Ops integration config:**
- Endpoint: `http://jenkins.stella-ops.local:8080`
- AuthRef: `authref://vault/jenkins#api-token`

**Create an API token:**
1. Open Jenkins > Manage Jenkins > Users > admin > Configure
2. Add API Token
3. Store in Vault at `secret/jenkins` with key `api-token`

---

### Nexus (Repository Manager)

| Property | Value |
|----------|-------|
| URL | http://nexus.stella-ops.local:8081 |
| API | http://nexus.stella-ops.local:8081/service/rest/v1/status |
| Docker hosted | nexus.stella-ops.local:8082 |
| Docker proxy | nexus.stella-ops.local:8083 |
| Admin | admin / *(see `/nexus-data/admin.password` on first run)* |
| Integration type | Registry (Nexus provider) |
| Docker DNS | `nexus.stella-ops.local` |

**Get initial admin password:**
```bash
docker exec stellaops-nexus cat /nexus-data/admin.password
```

**Stella Ops integration config:**
- Endpoint: `http://nexus.stella-ops.local:8081`
- AuthRef: `authref://vault/nexus#admin-password`

**Setup Docker hosted repository:**
1. Login to Nexus UI
2. Server Administration > Repositories > Create > docker (hosted)
3. HTTP port: 8082, Allow redeploy: true
4. Create a docker (proxy) repository pointing to Docker Hub, HTTP port: 8083

---

### HashiCorp Vault (Secrets)

| Property | Value |
|----------|-------|
| URL | http://vault.stella-ops.local:8200 |
| API | http://vault.stella-ops.local:8200/v1/sys/health |
| Root token | `stellaops-dev-root-token-2026` |
| Mode | Dev server (in-memory, unsealed) |
| Integration type | Secrets (Vault provider) |
| Docker DNS | `vault.stella-ops.local` |

**Stella Ops integration config:**
- Endpoint: `http://vault.stella-ops.local:8200`
- AuthRef: (Vault is the auth provider itself)

**Store integration credentials in Vault:**
```bash
# Enable KV v2 engine (already enabled in dev mode at secret/)
export VAULT_ADDR=http://vault.stella-ops.local:8200
export VAULT_TOKEN=stellaops-dev-root-token-2026

# Store Harbor credentials
vault kv put secret/harbor robot-account="harbor-robot-token"

# Store GitHub App credentials
vault kv put secret/github app-private-key="-----BEGIN RSA PRIVATE KEY-----..."

# Store Gitea API token
vault kv put secret/gitea api-token="your-gitea-token"

# Store Jenkins API token
vault kv put secret/jenkins api-token="your-jenkins-token"

# Store Nexus admin password
vault kv put secret/nexus admin-password="your-nexus-password"
```

---

### Docker Registry (OCI v2)

| Property | Value |
|----------|-------|
| URL | http://registry.stella-ops.local:5000 |
| API | http://registry.stella-ops.local:5000/v2/ |
| Auth | None (open dev registry) |
| Integration type | Registry (generic OCI) |
| Docker DNS | `registry.stella-ops.local` |

**Push a test image:**
```bash
docker tag alpine:latest registry.stella-ops.local:5000/test/alpine:latest
docker push registry.stella-ops.local:5000/test/alpine:latest

# List repositories
curl http://registry.stella-ops.local:5000/v2/_catalog
```

**Stella Ops integration config:**
- Endpoint: `http://registry.stella-ops.local:5000`
- AuthRef: *(none required for dev)*

---

### MinIO (S3 Storage)

| Property | Value |
|----------|-------|
| Console | http://minio.stella-ops.local:9001 |
| S3 API | http://minio.stella-ops.local:9000 |
| Access key | `stellaops` |
| Secret key | `Stella2026!` |
| Docker DNS | `minio.stella-ops.local` |

**Create buckets for Stella Ops:**
```bash
# Install mc CLI
docker exec stellaops-minio mc alias set local http://localhost:9000 stellaops Stella2026!

# Create buckets
docker exec stellaops-minio mc mb local/evidence-locker
docker exec stellaops-minio mc mb local/airgap-bundles
docker exec stellaops-minio mc mb local/scan-results
docker exec stellaops-minio mc mb local/sbom-archive
```

---

### GitLab CE (Heavy, Optional)

| Property | Value |
|----------|-------|
| URL | http://gitlab.stella-ops.local:8929 |
| Admin | root / `Stella2026!` |
| SSH | gitlab.stella-ops.local:2224 |
| Container Registry | gitlab.stella-ops.local:5050 |
| RAM required | 4 GB+ |
| Startup time | ~3-5 minutes |
| Integration type | SCM + CI/CD + Registry |
| Docker DNS | `gitlab.stella-ops.local` |

**Start GitLab (uses `heavy` profile):**
```bash
docker compose -f docker-compose.integrations.yml --profile heavy up -d gitlab
```

**Stella Ops integration config (SCM):**
- Endpoint: `http://gitlab.stella-ops.local:8929`
- AuthRef: `authref://vault/gitlab#access-token`

---

## Mock Fixtures

In addition to real services, lightweight nginx-based fixtures provide deterministic mock APIs for UI testing.

| Fixture | Mocks | Address | Compose file |
|---------|-------|---------|-------------|
| harbor-fixture | Harbor v2 API | 127.1.1.6:80 | docker-compose.integration-fixtures.yml |
| github-app-fixture | GitHub App API | 127.1.1.7:80 | docker-compose.integration-fixtures.yml |
| advisory-fixture | CERT-In, FSTEC, VEX Hub, StellaOps Mirror, etc. | 127.1.1.8:80 | docker-compose.integration-fixtures.yml |

```bash
# Start fixtures only
docker compose -f docker-compose.integration-fixtures.yml up -d
```

---

## IP Address Map

| IP | Service | Port(s) |
|----|---------|---------|
| 127.1.0.1 | stella-ops.local (gateway) | 443 |
| 127.1.0.4 | authority (OIDC) | 80 |
| 127.1.1.1 | postgres | 5432 |
| 127.1.1.2 | valkey | 6379 |
| 127.1.1.6 | harbor-fixture | 80 |
| 127.1.1.7 | github-app-fixture | 80 |
| 127.1.1.8 | advisory-fixture | 80 |
| 127.1.2.1 | gitea | 3000, 2222 |
| 127.1.2.2 | jenkins | 8080, 50000 |
| 127.1.2.3 | nexus | 8081, 8082, 8083 |
| 127.1.2.4 | vault | 8200 |
| 127.1.2.5 | docker-registry | 5000 |
| 127.1.2.6 | minio | 9000, 9001 |
| 127.1.2.7 | gitlab (heavy) | 8929, 2224, 5050 |

---

## Volumes

All service data persists in named Docker volumes. To reset a service:

```bash
# Stop and remove a specific service + its volume
docker compose -f docker-compose.integrations.yml down -v nexus
docker volume rm stellaops-nexus-data

# Reset ALL integration services
docker compose -f docker-compose.integrations.yml down -v
```

---

## Integration Matrix

| Stella Ops Category | Provider | Local Service | Status |
|---------------------|----------|---------------|--------|
| **Registry** | Harbor | harbor-fixture (mock) | Ready |
| **Registry** | Docker Hub / OCI | docker-registry | Ready |
| **Registry** | Nexus | nexus | Ready |
| **Registry** | GitLab Registry | gitlab (heavy) | Optional |
| **SCM** | GitHub App | github-app-fixture (mock) | Ready |
| **SCM** | Gitea | gitea | Ready |
| **SCM** | GitLab Server | gitlab (heavy) | Optional |
| **CI/CD** | Jenkins | jenkins | Ready (needs plugin) |
| **CI/CD** | GitLab CI | gitlab (heavy) | Optional (needs plugin) |
| **Secrets** | Vault | vault | Ready |
| **Storage** | S3 (MinIO) | minio | Ready |
| **Advisory & VEX** | 74 sources | advisory-fixture + live | 74/74 healthy |

> **Note:** CI/CD and Runtime Host integrations require backend connector plugins to be loaded
> in the Integrations service. Currently only Harbor, GitHub App, GitLab, and InMemory plugins
> are compiled into the service.