# LotusCloud Local Guide (Deploy / Run / Build / Test)

This guide is the single reference to run LotusCloud locally on Windows with Docker.

## 1. Prerequisites

- Docker Desktop (running)
- VS Code terminal at repo root: `C:\Users\Mr.Robert\source\vscode\LotusCloud`

Optional:
- Go 1.24+ only if you want to run `go test` directly outside containers

## 2. Start services

Optional one-time Windows setup:

```powershell
./scripts/setup-windows.ps1
```

1. Create env file:

```powershell
Copy-Item .env.example .env
```

Then update required secrets in `.env` before first run:
- `POSTGRES_PASSWORD`
- `JWT_SECRET`
- `GRAFANA_ADMIN_USER`
- `GRAFANA_ADMIN_PASSWORD`

2. Build and run all services, including the frontend container:

```powershell
docker compose up --build -d
```

Or use the Windows helper script:

```powershell
./scripts/docker-up.ps1
```

3. Check status:

```powershell
docker compose ps
```

Expected host endpoints:
- API Gateway: `http://localhost:8080`
- Lotus Console: `http://localhost:3100`
- Prometheus: `http://localhost:9090`
- Grafana: `http://localhost:3000`

Internal services (IAM/Compute/Storage/Network/Billing) are exposed only inside the Docker network by default.

## 3. Smoke test (end-to-end)

### 3.1 Register and login via gateway

```powershell
$base='http://localhost:8080'
$reg=@{email='admin@lotuscloud.vn';password='StrongPass123!';full_name='Admin'}|ConvertTo-Json
try { Invoke-RestMethod -Method Post -Uri "$base/api/v1/auth/register" -ContentType 'application/json' -Body $reg | Out-Null } catch {}
$login=Invoke-RestMethod -Method Post -Uri "$base/api/v1/auth/login" -ContentType 'application/json' -Body (@{email='admin@lotuscloud.vn';password='StrongPass123!'}|ConvertTo-Json)
$token=$login.data.access_token
$authHeaders=@{ Authorization = "Bearer $token"; 'Content-Type'='application/json' }
```

### 3.2 Create project and call Phase 2 APIs

```powershell
$pname='demo-'+[guid]::NewGuid().ToString().Substring(0,8)
$project=Invoke-RestMethod -Method Post -Uri "$base/api/v1/projects" -Headers $authHeaders -Body (@{name=$pname}|ConvertTo-Json)
$projectId=$project.data.id
$headers=@{ Authorization = "Bearer $token"; 'X-Project-ID' = "$projectId"; 'Content-Type'='application/json' }

Invoke-RestMethod -Method Post -Uri "$base/api/v1/instances" -Headers $headers -Body (@{name='vm-01';region='hanoi';flavor='lc.small'}|ConvertTo-Json)
Invoke-RestMethod -Method Post -Uri "$base/api/v1/buckets" -Headers $headers -Body (@{name=('bucket-'+[guid]::NewGuid().ToString().Substring(0,6));region='hanoi'}|ConvertTo-Json)
Invoke-RestMethod -Method Post -Uri "$base/api/v1/vpcs" -Headers $headers -Body (@{name='vpc-a';cidr='10.10.0.0/16';region='hanoi'}|ConvertTo-Json)
```

### 3.3 Event-driven billing (automatic)

After creating compute/storage/network resources, billing usage is automatically updated by service events.

```powershell
Invoke-RestMethod -Method Get -Uri "$base/api/v1/billing/usage" -Headers $headers
Invoke-RestMethod -Method Get -Uri "$base/api/v1/billing/cost-breakdown" -Headers $headers
Invoke-RestMethod -Method Get -Uri "$base/api/v1/billing/invoices" -Headers $headers
```

### 3.4 Optional demo seed and SKU query

```powershell
Invoke-RestMethod -Method Post -Uri "$base/api/v1/billing/seed" -Headers $headers
Invoke-RestMethod -Method Get -Uri "$base/api/v1/billing/skus" -Headers $headers
```

## 4. Build images only

```powershell
docker compose build
```

## 5. Run tests

### Fast path on Windows

```powershell
./scripts/test-backend.ps1
./scripts/test-integration.ps1
./scripts/verify-stack.ps1
```

Or use Make targets if `make` is installed:

```powershell
make up
make test
make integration-test
make verify
```

### Option A: If Go is installed locally

```powershell
cd services/iam-service; go test ./...; cd ../..
cd services/api-gateway; go test ./...; cd ../..
cd services/compute-service; go test ./...; cd ../..
cd services/storage-service; go test ./...; cd ../..
cd services/network-service; go test ./...; cd ../..
cd services/billing-service; go test ./...; cd ../..
```

### Option B: Without local Go (inside temporary golang container)

```powershell
docker run --rm -v ${PWD}:/src -w /src/services/iam-service golang:1.24-alpine sh -lc "go test ./..."
docker run --rm -v ${PWD}:/src -w /src/services/api-gateway golang:1.24-alpine sh -lc "go test ./..."
docker run --rm -v ${PWD}:/src -w /src/services/compute-service golang:1.24-alpine sh -lc "go test ./..."
docker run --rm -v ${PWD}:/src -w /src/services/storage-service golang:1.24-alpine sh -lc "go test ./..."
docker run --rm -v ${PWD}:/src -w /src/services/network-service golang:1.24-alpine sh -lc "go test ./..."
docker run --rm -v ${PWD}:/src -w /src/services/billing-service golang:1.24-alpine sh -lc "go test ./..."
```

### Integration test via Gateway

```powershell
$root='/c/Users/Mr.Robert/source/vscode/LotusCloud'
docker run --rm -v "${root}:/src" -w /src/tests/integration -e BASE_URL=http://host.docker.internal:8080 golang:1.24-alpine sh -c "go test -tags=integration ./..."

# If go.work is detected from repo root, disable it for this standalone module:
docker run --rm -v "${root}:/src" -w /src/tests/integration -e BASE_URL=http://host.docker.internal:8080 -e GOWORK=off golang:1.24-alpine sh -c "go test -tags=integration ./..."
```

## 6. Stop and cleanup

```powershell
docker compose down
```

Or:

```powershell
./scripts/docker-down.ps1
```

Remove volumes too:

```powershell
docker compose down -v
```

## 7. Notes

- Gateway now enforces auth on all Phase 2 routes (Compute/Storage/Network/Billing).
- For resource APIs, always include `X-Project-ID` header.
- Billing supports automatic usage ingestion from compute/storage/network events.
- Billing also has demo seeding endpoint: `POST /api/v1/billing/seed`.
- Legacy billing endpoint `POST /api/v1/billing/events` is disabled by default. Enable only if needed with `LEGACY_EVENTS_ENDPOINT_ENABLED=true`.
- Event consumer metrics are logged periodically; tune with `EVENT_METRICS_LOG_INTERVAL_SEC`.
- Billing metrics endpoint is internal-only and scraped by Prometheus via the Docker network.
- Grafana auto-provisions Prometheus datasource and dashboard from `infrastructure/observability/grafana/dashboards/billing-consumer-metrics.json`.
- Default Grafana login is controlled by `.env` (`GRAFANA_ADMIN_USER` / `GRAFANA_ADMIN_PASSWORD`).
- VS Code Windows tasks are defined in `.vscode/tasks.json`.
- Backend and observability services now have Docker healthchecks; gateway and frontend wait for healthy upstreams before becoming ready.
- CI generates `.env` from `.env.ci.example` via `./scripts/generate-ci-env.sh` and uses cached Go, Node, and Docker Buildx layers.