stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
404d50bcb74da4617575a099950ef375af88ed2f
git.stella-ops.org/docs/integrations/LOCAL_SERVICES.md
master 89a075ea21 Add integration connector plugins and compose fixtures 
Scaffold connector plugins for DockerRegistry, GitLab, Gitea,
Jenkins, and Nexus. Wire plugin discovery in IntegrationService
and add compose fixtures for local integration testing.

- 5 new connector plugins under src/Integrations/__Plugins/
- docker-compose.integrations.yml for local fixture services
- Advisory source catalog and source management API updates
- Integration e2e test specs and Playwright config
- Integration hub docs under docs/integrations/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-30 17:24:56 +03:00

342 lines
11 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink