First-Run Setup Guide

Version: 1.0 Last Updated: 2026-01-31 Status: Active

---

Overview

This guide covers the first-time setup of the Sorcha platform. The setup wizard handles:

• Environment Detection: Checks for Docker, .NET SDK, and port availability
• Configuration Generation: Creates .env file with secure credentials
• Infrastructure Provisioning: Creates Docker volumes and starts database services
• Service Startup: Builds and starts all application services
• Validation: Verifies all services are healthy and accessible

Prerequisites

Required

Component	Version	Download
Docker Desktop	4.0+	docker.com
Docker Compose	2.0+ (plugin) or 1.29+ (standalone)	Included with Docker Desktop

Optional (for development)

Component	Version	Download
.NET SDK	10.0+	dotnet.microsoft.com
Git	2.30+	git-scm.com
Sorcha CLI	Latest	dotnet tool install -g Sorcha.Cli

Quick Start

Windows (PowerShell)

# Clone the repository
git clone https://github.com/sorcha-platform/sorcha.git
cd Sorcha

# Run the setup wizard
.\scripts\setup.ps1

Linux / macOS (Bash)

# Clone the repository
git clone https://github.com/sorcha-platform/sorcha.git
cd Sorcha

# Make scripts executable
chmod +x scripts/*.sh

# Run the setup wizard
./scripts/setup.sh

Setup Wizard Steps

The setup wizard performs these steps automatically:

1. Prerequisites Check

Verifies that required software is installed:

[1/8] Checking Prerequisites
--------------------------------------------------
  [OK] Docker CLI found
  [OK] Docker daemon is running
  [OK] Docker Compose found (plugin)
  [OK] .NET SDK 10.0.100 found
  [OK] Git found

2. Port Availability

Checks that required ports are not in use:

Port	Service
80	API Gateway (HTTP)
443	API Gateway (HTTPS)
5000	Blueprint Service
5380	Register Service
5400	UI Web
5432	PostgreSQL
5450	Tenant Service
5800	Validator Service
16379	Redis
18888	Aspire Dashboard
27017	MongoDB

3. First-Run Detection

Detects if this is a fresh installation by checking for:

• Missing .env file
• Missing Docker volumes
• Missing Sorcha containers

4. Configuration Generation

Creates .env file with:

• Installation name: Used for JWT issuer (default: localhost)
• JWT signing key: Auto-generated 256-bit key
• Database credentials: Development defaults

# Generated .env file
INSTALLATION_NAME=localhost
JWT_SIGNING_KEY=<auto-generated-256-bit-key>
POSTGRES_USER=sorcha
POSTGRES_PASSWORD=sorcha_dev_password

5. Docker Volumes

Creates persistent storage volumes:

• sorcha_redis-data
• sorcha_postgres-data
• sorcha_mongodb-data
• sorcha_dataprotection-keys
• sorcha_wallet-encryption-keys

6. Infrastructure Services

Starts and waits for infrastructure services:

• Redis (caching, session, pub/sub)
• PostgreSQL (Tenant, Wallet databases)
• MongoDB (Register database)
• Aspire Dashboard (observability)

7. Application Services

Builds and starts all microservices:

• Blueprint Service
• Wallet Service
• Register Service
• Tenant Service
• Validator Service
• Peer Service
• API Gateway
• UI Web

8. Validation

Verifies all services are healthy and accessible.

Post-Setup: Bootstrap

After setup completes, the Tenant Service creates the default organization, admin user, and service principals automatically on first start. No separate bootstrap script is needed for the standard Docker flow.

To confirm bootstrap succeeded, check the tenant-service logs:

docker-compose logs tenant-service | grep -i "bootstrap\|principal\|admin"

The default credentials are:

• Admin user: admin@sorcha.local / Dev_Pass_2025!
• Service principal secrets are logged at WARNING level on first boot (save them — they are not shown again).

If you need to seed additional organizations or test data, use the seed scripts:

# Windows — seed tenant service with sample data
.\scripts\seed-tenant-service.ps1

# Bash
./scripts/seed-tenant-service.sh

See Bootstrap Credentials for the full credential reference.

Service URLs

After setup and bootstrap, access services at:

Service	URL	Purpose
Main UI	http://localhost/app	Primary user interface
API Gateway	http://localhost	REST API endpoints
API Documentation	http://localhost/scalar	OpenAPI/Scalar docs
Aspire Dashboard	http://localhost:18888	Observability

Troubleshooting

Docker Not Running

[X] Docker Desktop is not running

Solution: Start Docker Desktop and wait for it to initialize.

Port Already in Use

[X] Port 80 in use (API Gateway HTTP)

Solution: Stop the conflicting service or modify docker-compose.yml to use a different port:

# Find what's using the port
netstat -ano | findstr :80  # Windows
lsof -i :80                  # Linux/macOS

# Kill the process
taskkill /PID <pid> /F       # Windows
kill -9 <pid>                # Linux/macOS

Wallet Encryption Permissions

[!] Could not set wallet permissions

Solution: Run the permissions fix script:

# PowerShell
.\scripts\fix-wallet-encryption-permissions.ps1

# Bash
./scripts/fix-wallet-encryption-permissions.sh

Services Not Starting

Check the logs for specific errors:

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f tenant-service

HTTPS Not Working

HTTPS requires a certificate mounted at docker/certs/aspnetapp.pfx. The docker-compose.yml mounts ./docker/certs:/https:ro into the gateway. Generate a dev certificate with the existing script:

# Windows
.\scripts\generate-dev-cert.ps1

Or manually:

mkdir -p docker/certs
dotnet dev-certs https -ep docker/certs/aspnetapp.pfx -p SorchaDev2025 --trust

Restart the gateway after generating the certificate:

docker-compose restart api-gateway

Environment Validation

Run the validation script to check environment health:

# Windows — full validation
.\scripts\validate-environment.ps1

# Quick check (summary only)
.\scripts\validate-environment.ps1 -Quiet

# JSON output (for CI/CD)
.\scripts\validate-environment.ps1 -JsonOutput

This script exists at scripts/validate-environment.ps1. There is no Bash equivalent; on Linux/macOS use docker-compose ps and the health endpoints directly:

curl -s http://localhost/health
docker-compose ps

Advanced Options

Non-Interactive Setup

For CI/CD or scripted deployments:

.\scripts\setup.ps1 -NonInteractive

Skip Docker Checks

For environments where Docker validation should be skipped:

.\scripts\setup.ps1 -SkipDocker

Force Re-initialization

To regenerate configuration even if already set up:

.\scripts\setup.ps1 -Force

Verbose Output

For detailed troubleshooting:

.\scripts\setup.ps1 -Verbose

Configuration Reference

The setup wizard creates a .env file with these variables:

Variable	Description	Default
INSTALLATION_NAME	JWT issuer identifier	localhost
JWT_SIGNING_KEY	256-bit signing key	Auto-generated
POSTGRES_USER	PostgreSQL username	sorcha
POSTGRES_PASSWORD	PostgreSQL password	sorcha_dev_password
MONGO_USERNAME	MongoDB username	sorcha
MONGO_PASSWORD	MongoDB password	sorcha_dev_password
ASPNETCORE_ENVIRONMENT	Runtime environment	Development

Production Configuration

For production deployments, update these values:

1. Generate new secrets:

   # Generate new JWT key
   [Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

2. Update .env:

   INSTALLATION_NAME=sorcha.mycompany.com
   JWT_SIGNING_KEY=<new-256-bit-key>
   POSTGRES_PASSWORD=<strong-password>
   MONGO_PASSWORD=<strong-password>
   ASPNETCORE_ENVIRONMENT=Production

3. Enable HTTPS (see HTTPS Setup)

Related Documentation

• Port Configuration - Complete port reference
• Authentication Setup - JWT and auth configuration
• Architecture Overview - System architecture
• Development Status - Current completion status

---

Document Owner: Sorcha Contributors Last Review: 2026-01-31