Service Startup and Shutdown Procedures

This document describes the startup and shutdown procedures for all environments (development, smoke, production).

Overview

The platform uses Docker Compose for service orchestration. Services are defined in the service registry (standards/service-registry.yaml) and generated into docker-compose.yml files.

Service Registry

All services are registered in standards/service-registry.yaml. The registry is the single source of truth for service configuration.

⚠️ CRITICAL: Never hand-edit docker-compose.yml directly. Always edit the service registry and run make registry-first to regenerate.

Development / Local Evaluation (Docker Compose)

Startup

Quickstart:

./scripts/bootstrap-env.sh
docker compose up -d

docker compose automatically loads docker-compose.override.yml alongside docker-compose.yml, which is what makes this a single command — see INSTALL.md for the full walkthrough.

Manual, staged Startup (useful when debugging a specific service):

# 1. Start infrastructure
docker compose up -d postgres redis nats

# 2. Wait for infrastructure (10-30 seconds)
sleep 10

# 3. Start backend services
docker compose up -d auth-service inventory-service compliance-engine \
  cbom-service sensor-manager admin-service cluster-sensor-service \
  monitoring-service tenant-health-service \
  device-interrogation-service audit-service notification-service \
  discovery-processor-service pcap-processor mcp-service

# 4. Start API gateway (before frontend so UIs can reach the API)
docker compose up -d api-gateway
# The API gateway serves both v1 and v2; Traefik config is generated from the registry.

# 5. Start frontend
docker compose up -d web-ui admin-ui

Service Order: 1. Infrastructure (postgres, redis, nats) 2. Backend services (all can start in parallel after infrastructure) 3. API Gateway 4. Frontend applications

Shutdown

Manual Shutdown:

docker compose down

Complete Cleanup (removes all data):

docker compose down -v
# or, if you need the volumes' host-side artifacts cleaned too:
./scripts/clean-all-volumes.sh

Service Validation

After startup, validate all services — there is no bundled validation script:

docker compose ps
curl -sf http://localhost:8080/api/v1/auth-service/health
curl -sf http://localhost:3000  # web UI
curl -sf http://localhost:3006  # admin UI

This checks: - All containers report Up/healthy in docker compose ps - API Gateway routes through to a backend health endpoint - Frontend accessibility (web UI and admin UI)

Production Environment (Kubernetes)

There is no docker-compose.prod.yml or EC2-based production path in this repository — production installs use the Helm chart (charts/vistaplatform/) against any Kubernetes cluster. See INSTALL.md ("Run it") for the quick path, or Service-mesh mTLS for staging internal mTLS on an existing production cluster.

Startup / Shutdown

# Evaluation only: --set agentMtls.enabled=false opts out of agent/sensor
# client-certificate authentication. A real install sets the two
# agentMtls.backends.<svc>.dnsName hostnames instead (see INSTALL.md "Run it").
helm install vista oci://ghcr.io/vistasecurity/vistaplatform \
  --namespace vista --create-namespace --wait \
  --set agentMtls.enabled=false

helm uninstall vista --namespace vista

Service Validation

kubectl -n vista get pods
kubectl -n vista logs deployment/notification-service

Service Dependencies

Infrastructure Services

These lists are derived from standards/service-registry.yaml, which is the single source of truth the Compose files and the Helm chart are generated from. If a service is added or its datastores change, update the registry — this page is a mirror and will otherwise drift, as it did before v0.12.5.

• PostgreSQL: primary datastore — required by 14 service(s): admin-service, audit-service, auth-service, cbom-service, cluster-sensor-service, compliance-engine, device-interrogation-service, discovery-processor-service, inventory-service, monitoring-service, notification-service, pcap-processor, sensor-manager, tenant-health-service
• Redis: caching, sessions, and the JWT revocation denylist — required by 12 service(s): admin-service, audit-service, auth-service, cbom-service, cluster-sensor-service, compliance-engine, device-interrogation-service, inventory-service, monitoring-service, notification-service, sensor-manager, tenant-health-service
• NATS: message queue — required by 13 service(s): admin-service, audit-service, cbom-service, cluster-sensor-service, compliance-engine, device-interrogation-service, discovery-processor-service, inventory-service, monitoring-service, notification-service, pcap-processor, sensor-manager, tenant-health-service

Backend Service Dependencies

• admin-service: nats, postgres, redis
• audit-service: nats, postgres, redis
• auth-service: postgres, redis
• cbom-service: nats, postgres, redis
• cluster-sensor-service: nats, postgres, redis
• Requires CLUSTER_SENSOR_SERVICE_TOKEN for auto-registration
• Auto-registers platform discovery sensor for all tenants on startup
• compliance-engine: nats, postgres, redis
• device-interrogation-service: nats, postgres, redis
• Uses the per-tenant device_interrogation system sensor created by the database trigger; it does not auto-register a duplicate fleet agent
• Operator-installed agents enroll with a registration key and tenant certificate

Upgraded installations may retain a historical platform entry in the device agent fleet. It no longer receives a heartbeat and can raise the ordinary offline-agent alert until an operator deletes it through the agent fleet or agent API. Removing that obsolete row does not affect the system sensor or the in-cluster interrogation worker.

• discovery-processor-service: nats, postgres
• inventory-service: nats, postgres, redis
• mcp-service: none
• monitoring-service: nats, postgres, redis
• notification-service: nats, postgres, redis
• pcap-processor: nats, postgres
• sensor-manager: nats, postgres, redis
• tenant-health-service: nats, postgres, redis

Service-to-Service Dependencies

• monitoring-service → notification-service (for alerts)
• cluster-sensor-service → notification-service (for discovery alerts)
• audit-service → notification-service (for security alerts)

Notification Service Configuration

Environment Variables

Required: - DATABASE_URL: PostgreSQL connection string - JWT_SECRET: JWT signing secret - ENCRYPTION_MASTER_KEY: For decrypting email configuration

Optional: - PORT: Service port (default: 8080) - ENV: Environment (development, smoke, production) - LOG_LEVEL: Logging level (debug, info, warn, error) - NOTIFICATION_SERVICE_URL: URL for other services to call (default: http://notification-service:8080)

Service Startup Order

Notification service should start after: 1. PostgreSQL (database) 2. Other services that send notifications (monitoring, discovery, audit)

Notification service can start in parallel with other backend services.

Health Check

# Check notification service health
curl http://localhost:8097/health

# Expected response:
# {"status":"healthy","service":"notification-service"}

Troubleshooting

Service Won't Start

1. Check logs:

   docker compose logs notification-service
   

2. Check database connectivity:

   docker compose exec postgres psql -U crypto_user -d crypto_inventory -c "SELECT 1;"
   

3. Check environment variables:

   docker compose exec notification-service env | grep -E "(DATABASE|JWT|ENCRYPTION)"
   

4. Check port availability:

   netstat -tuln | grep 8097
   

Service Starts But Crashes

1. Check database schema:

   docker compose exec postgres psql -U crypto_user -d crypto_inventory -c "\dt tenant_notification*"
   

2. Check the schema is applied (there is no migration runner — the schema is loaded from scripts/database/schema.sql, so there is no schema_migrations version table; verify expected tables exist instead):

   docker compose exec postgres psql -U crypto_user -d crypto_inventory -c "\dt" | head -20
   

3. Check service logs for errors:

   docker compose logs --tail=100 notification-service
   

Notifications Not Sending

1. Check notification service is running:

   docker compose ps notification-service
   

2. Check notification history:

   SELECT * FROM notification_history ORDER BY created_at DESC LIMIT 10;
   

3. Check channel configuration:

   SELECT * FROM tenant_notification_channels WHERE enabled = true;
   

4. Test channel connectivity:

5. Use UI: Settings → Notifications → Channels → Test
6. Or API: POST /api/v1/notification-service/tenant/channels/:id/test

Related Documentation

• Service Validation - manual validation commands above (there is no bundled validation script)
• Notification Provider Integration Guide - Third-party integration setup