Installation Handbook Epic

User Journey

The Installation bounded context provides multiple installation methods for SEA-Forge™ including DevContainer, CLI installation, and native development setup. It enables quick start for VS Code/Codespaces users, Zed IDE integration, and provides configuration management and health check capabilities.

Jobs to be Done & EARS Requirements

Job: Install via DevContainer

User Story: As a VS Code user, I want a zero-config development environment with all dependencies pre-installed, so that I can start working immediately.

EARS Requirement:

• While setting up development environment, when DevContainer method is used, the installation context shall:
  1. Verify Prerequisites:
     • Docker Desktop is installed and running
     • VS Code is installed
     • Dev Containers extension is installed
  2. Clone Repository:
     • Execute git clone https://github.com/GodSpeedAI/SEA.git
     • Open repository in VS Code with code SEA
  3. Reopen in Container:
     • Detect .devcontainer configuration
     • Prompt user to click “Reopen in Container”
     • Build container image and install dependencies
     • Complete setup in ~5 minutes on first run
  4. Verify Installation:
     • Run just doctor to check prerequisites
     • Return success confirmation with environment status

Job: Install CLI from Cargo

User Story: As a developer, I want to install the SEA-Forge CLI tool globally, so that I can run SEA-Forge commands from any directory.

EARS Requirement:

• While installing CLI, when cargo install is executed, the installation context shall:
  1. From Cargo (after release):
     • Execute cargo install sea-forge
     • Download and compile SEA-Forge binary
     • Install to global cargo bin directory
     • Verify with sea-forge --version
  2. From Source:
     • Clone repository with git clone https://github.com/GodSpeedAI/SEA.git
     • Change to SEA directory
     • Execute just install-cli
     • Build and install CLI locally
     • Verify with sea-forge doctor

Job: Configure Native Development Setup

User Story: As a Zed IDE user, I want to set up native development environment, so that I can use SEA-Forge with my preferred editor.

EARS Requirement:

• While setting up native development, when native setup is executed, the installation context shall:
  1. Clone Repository:
     • Execute git clone https://github.com/GodSpeedAI/SEA.git
     • Change to SEA directory
  2. Run Setup:
     • Execute just setup to install dependencies
     • Configure project settings
     • Initialize development environment
  3. Configure Zed IDE:
     • Execute just ui-setup for Zed configuration
     • Set up ACP agent in ~/.config/zed/settings.json
     • Configure agent command: python -m libs.sea.adapters.acp.src.cli
     • Set working directory to SEA project path
  4. Start Services:
     • Execute sea-forge up or just ui-up
     • Launch all required services
     • Display service URLs and status

Job: Check Prerequisites and Health

User Story: As a developer, I want to verify my environment is correctly configured, so that I can troubleshoot installation issues.

EARS Requirement:

• While checking environment, when sea-forge doctor or just doctor is executed, the installation context shall:
  1. Check Required Tools:
     • Docker: Verify version 24+
     • docker-compose: Verify version 2.20+
     • Node.js: Verify version 18+
     • Python: Verify version 3.11+
     • just: Verify version 1.0+
  2. Check Service Availability:
     • PostgreSQL: Test connection on port 5432
     • NATS: Test connection on port 4222/8222
     • Oxigraph: Test connection on port 7878
     • OTel Collector: Test connection on port 4317
  3. Check Configuration:
     • Verify sea-forge.yaml exists (or create from example)
     • Validate required environment variables are set
     • Check file system permissions
  4. Generate Health Report:
     • List all checks with status (✓/✗)
     • Provide specific error messages for failed checks
     • Suggest remediation steps for each failure
     • Return overall health status (healthy/degraded/unhealthy)

Job: Start All Services

User Story: As a developer, I want to start all SEA-Forge services with a single command, so that I have a complete development environment.

EARS Requirement:

• While starting services, when sea-forge up or just ui-up is executed, the installation context shall:
  1. Read Configuration from sea-forge.yaml
  2. Start Services in dependency order:
     • Infrastructure: PostgreSQL, NATS, Oxigraph
     • Observability: OTel Collector
     • Application: All bounded contexts
     • UI: LibreChat, Zed agent
  3. Enable Watch Mode (if --watch flag):
     • Monitor service health
     • Restart failed services automatically
     • Log restart events
  4. Display Status:
     • Show service URLs (LibreChat, Portal, etc.)
     • Indicate service health with icons (✓/✗)
     • Provide access instructions for each UI

Job: Stop All Services

User Story: As a developer, I want to stop all SEA-Forge services to free resources, so that I can shut down cleanly.

EARS Requirement:

• While stopping services, when sea-forge down is executed, the installation context shall:
  1. Stop Services in reverse dependency order
  2. Graceful Shutdown:
     • Allow in-flight requests to complete
     • Flush pending writes
     • Close network connections
  3. Cleanup Resources:
     • Remove temporary files
     • Clear any locks
     • Release ports
  4. Display Confirmation with stopped service list

Job: Apply Declarative Configuration

User Story: As a platform engineer, I want to apply declarative state from sea-forge.yaml, so that infrastructure matches specification.

EARS Requirement:

• While applying configuration, when sea-forge apply is executed, the installation context shall:
  1. Read Current State from running services
  2. Read Desired State from sea-forge.yaml
  3. Calculate Diff:
     • Identify services to create
     • Identify services to update
     • Identify services to delete
  4. Apply Changes:
     • Create new services with specified configuration
     • Update existing services to match desired state
     • Delete services not in desired state (with confirmation)
  5. Return Apply Result with changes made

Job: Check Service Status

User Story: As a developer, I want to check the health of all running services, so that I can identify and troubleshoot issues.

EARS Requirement:

• While checking status, when sea-forge status is executed, the installation context shall:
  1. Query Service Health Endpoints:
     • PostgreSQL: Connection test
     • NATS: Stream info check
     • Oxigraph: SPARQL endpoint test
     • Application services: HTTP health checks
  2. Aggregate Status:
     • Collect health status for each service
     • Calculate uptime percentages
     • Identify degraded or failed services
  3. Display Status Report:
     • Table format with service name, status, uptime, URL
     • Highlight failed services in red
     • Highlight degraded services in yellow
     • Show recent errors if any

Job: Customize Configuration

User Story: As a developer, I want to customize SEA-Forge configuration for my environment, so that services run with my preferred settings.

EARS Requirement:

• While configuring, when configuration is customized, the installation context shall:
  1. Copy Template:
     • Execute cp sea-forge.yaml.example sea-forge.yaml
     • Create editable configuration file
  2. Edit Configuration:
     • Set service versions and images
     • Configure port mappings
     • Set environment variables
     • Enable/disable features
     • Configure resource limits
  3. Validate Configuration:
     • Parse YAML syntax
     • Validate required fields
     • Check port conflicts
     • Verify image references
  4. Apply Configuration on next sea-forge up

Domain Entities Summary

Root Aggregates

• DevContainer: VS Code development container with pre-installed dependencies and tools
• CLIBinary: Compiled SEA-Forge executable installed globally via cargo
• ServiceInstance: Running service with health status, configuration, and endpoints
• ConfigurationFile: YAML configuration file with service definitions and settings

Value Objects

• HealthCheck: Service health validation with status (healthy/unhealthy/degraded) and details
• ServiceURL: Access endpoint with protocol, host, port, and path
• PrerequisiteCheck: Tool validation with name, version requirement, installed version, and status
• ConfigurationDiff: Difference between current and desired state with creates, updates, deletes

Policy Rules

• PrerequisiteVersion: All tools must meet minimum version requirements
• ServiceDependencyOrder: Services must start in dependency order
• GracefulShutdown: Services must allow in-flight requests to complete
• ConfigurationValidation: Configuration must be valid before applying

Integration Points

• Docker Desktop: Container runtime for DevContainer and service orchestration
• VS Code: IDE with Dev Containers extension for zero-config setup
• Zed IDE: Editor with ACP agent integration for native development
• cargo: Package manager for CLI installation
• just: Task runner for service management commands

Success Metrics

• Setup Time: <5 minutes for DevContainer, <10 minutes for CLI, <15 minutes for source
• Health Check Accuracy: 100% of service health correctly detected
• Service Start Time: <30 seconds for all services to be healthy
• Configuration Validation: 100% of configuration errors caught before apply

Non-Functional Requirements

• NFR-001: DevContainer includes all development dependencies
• NFR-002: CLI commands work from any directory
• NFR-003: Services start in dependency order automatically
• NFR-004: Configuration changes require explicit apply command