# Quickstart -- Local Dev Environment in Minutes

Get Stella Ops running locally for development and evaluation.

> This guide is for **local development**. For production deployment, see the [Installation Guide](INSTALL_GUIDE.md).

## Prerequisites

| Requirement | Minimum | Verify |
|-------------|---------|--------|
| OS | Windows 10+, macOS 12+, Ubuntu 22.04+ | x86-64 or arm64 |
| Docker | Engine 20.10+ with Compose v2 | `docker compose version` |
| .NET SDK | 10.x | `dotnet --version` |
| Node.js | 20+ | `node --version` |
| RAM | 16 GB (32 GB recommended) | |
| Disk | 50 GB free | |

## 1. Clone the repository

```bash
git clone <your-gitea-instance>/stella-ops/stella-ops.git
cd stella-ops
```

## 2. Run setup

**Windows (PowerShell 7):**

```powershell
.\scripts\setup.ps1
```

**Linux / macOS:**

```bash
./scripts/setup.sh
```

The setup script will:
- Verify all prerequisites are installed
- Offer to add hosts file entries (50 services need unique loopback IPs)
- Create `.env` from the example template (works out of the box, no editing needed)
- Build .NET solutions and Docker images
- Launch the full platform stack (`docker-compose.stella-ops.yml`)
- Run health checks and report status

### Infrastructure only (faster)

To skip builds and only start infrastructure:

```powershell
.\scripts\setup.ps1 -InfraOnly     # Windows
./scripts/setup.sh --infra-only    # Linux/macOS
```

## 3. First 30 minutes path

1. Start platform quickly (reuse existing images):
   ```powershell
   .\scripts\setup.ps1 -SkipBuild -SkipImages
   ```
2. Confirm service health:
   ```powershell
   docker compose -f devops/compose/docker-compose.stella-ops.yml ps
   ```
3. Preview demo seeding:
   ```powershell
   dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
     admin seed-demo --dry-run `
     --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
   ```
4. Seed demo data:
   ```powershell
   dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
     admin seed-demo --confirm `
     --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
   ```
5. Open **https://stella-ops.local**.

## What's running

After a full setup, you'll have 60+ services running locally:

| Service | URL | Purpose |
|---------|-----|---------|
| Web UI | https://stella-ops.local | Angular console |
| Authority | https://authority.stella-ops.local | OAuth2/OIDC |
| Scanner | https://scanner.stella-ops.local | SBOM/vulnerability scanning |
| Concelier | https://concelier.stella-ops.local | Advisory aggregation |
| PostgreSQL | db.stella-ops.local:5432 | Primary database |
| Valkey | cache.stella-ops.local:6379 | Cache and messaging |
| RustFS | s3.stella-ops.local:8333 | S3-compatible object storage |

Full service list: `devops/compose/docker-compose.stella-ops.yml`

Optional Sigstore services (`rekor-v2`, `rekor-cli`, `cosign`) are enabled only with:

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

## Troubleshooting

| Symptom | Meaning | Action |
|---------|---------|--------|
| `stella-ops.local` not found | Hosts entries missing | Re-run setup and accept hosts installation, or append `devops/compose/hosts.stellaops.local` manually |
| `health=starting` for RustFS during setup | Advisory startup lag | Wait 30-60 seconds and re-check `docker compose ... ps` |
| `stellaops-dev-rekor` restarting without `--profile sigstore` | Optional profile container from older runs | Non-blocking for default setup; ignore or clean old container |
| `SM remote service probe failed (localhost:56080)` in CLI | Optional China SM Remote plugin probe | Non-blocking for default crypto profile |
| `admin seed-demo --confirm` fails with `scheduler_exceptions_tenant_isolation already exists` | Outdated Scheduler migration scripts | Pull latest code and rerun seeding |
| Seed endpoint still returns HTTP 500 after patching source | Running old container image | Rebuild/restart platform image and retest |
| Port conflicts | Local process already using mapped port | Override in `devops/compose/.env` (`devops/compose/env/stellaops.env.example`) |

## Next steps

- [Developer setup details](dev/DEV_ENVIRONMENT_SETUP.md) -- manual steps, hybrid debugging, building individual modules
- [Installation Guide](INSTALL_GUIDE.md) -- production deployment, air-gap, regional compliance
- [Architecture overview](ARCHITECTURE_OVERVIEW.md) -- how the platform fits together