Powerhouse Hosting Package

A Powerhouse document model package for managing cloud hosting projects and environments. Built on the Powerhouse ecosystem, this package provides document models, editors, processors, and subgraphs for orchestrating cloud infrastructure.

Overview

This package provides two main document models:

• Project - Represents a hosting project that groups multiple environments
• Environment - Represents a deployable environment with Docker-like lifecycle management

Document Models

Project (vetra-cloud/project)

A project is a container for organizing related environments.

State:

{
  name: string;
  description: string | null;
  environments: Array<{
    id: string;
    name: string;
    environmentPHID: string;  // Reference to Environment document
  }>;
}

Operations: | Operation | Description | |-----------|-------------| | SET_PROJECT_NAME | Set the project name | | SET_PROJECT_DESCRIPTION | Set the project description | | ADD_ENVIRONMENT | Add an environment reference | | UPDATE_ENVIRONMENT | Update an environment reference | | REMOVE_ENVIRONMENT | Remove an environment reference |

Environment (vetra-cloud/environment)

An environment represents a deployable unit with services, app configuration, and lifecycle status.

State:

{
  name: string;
  status: EnvironmentStatus;
  services: {
    connect: boolean;
    switchboard: boolean;
  };
  app: {
    dockerImage: string;
    tag: string | null;
    port: number | null;
  } | null;
  databaseEnabled: boolean;
  backupsEnabled: boolean;
}

Status Lifecycle:

The environment follows a Docker-like container lifecycle:

                    ┌─────────────┐
                    │   CREATED   │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌─────────┐
        │ STARTING │ │DEPLOYING │ │  ERROR  │
        └────┬─────┘ └────┬─────┘ └────┬────┘
             │            │            │
             ▼            │            │
        ┌──────────┐      │            │
        │ RUNNING  │◄─────┘            │
        └────┬─────┘                   │
             │                         │
    ┌────────┼────────┬────────┐       │
    ▼        ▼        ▼        ▼       │
┌────────┐┌─────────┐┌───────────┐     │
│STOPPING││RESTARTING││MAINTENANCE│     │
└───┬────┘└────┬────┘└─────┬─────┘     │
    │          │           │           │
    ▼          │           │           │
┌────────┐     │           │           │
│ STOPPED│◄────┴───────────┴───────────┘
└────────┘

Operations: | Operation | Description | |-----------|-------------| | SET_ENVIRONMENT_NAME | Set the environment name | | SET_ENVIRONMENT_STATUS | Change status (validates transitions) | | SET_SERVICES | Enable/disable Connect and Switchboard | | SET_APP_CONFIG | Configure Docker app settings | | CLEAR_APP_CONFIG | Remove app configuration | | SET_DATABASE_ENABLED | Enable/disable database service | | SET_BACKUPS_ENABLED | Enable/disable backup service |

Processors

Environment Status Processor

Listens for status changes and executes lifecycle scripts.

// Script mapping
STARTING    → ./scripts/startEnv.sh
STOPPING    → ./scripts/stopEnv.sh
STOPPED     → ./scripts/cleanupEnv.sh
RESTARTING  → ./scripts/restartEnv.sh
DEPLOYING   → ./scripts/deployEnv.sh
MAINTENANCE → ./scripts/maintenanceEnv.sh
ERROR       → ./scripts/errorHandler.sh

Powerhouse Hosting DB Processor

A relational database processor that persists Project and Environment state to a SQL database for efficient querying.

Tables:

• projects - Project documents
• project_environments - Project-Environment relationships
• environments - Environment documents with full state

Editors

Project Editor

A visual editor for managing projects:

• Edit project name and description
• Add/remove environment references
• View linked environments

Environment Editor

A comprehensive editor for environment management:

• Status control with valid transition buttons
• Service toggles (Connect, Switchboard, Database, Backups)
• App configuration form (Docker image, tag, port)
• Color-coded status badges

Subgraphs

GraphQL subgraphs are provided for querying Projects and Environments:

# Project queries
query {
  Project {
    getDocument(docId: "...", driveId: "...")
    getDocuments(driveId: "...")
  }
}

# Environment queries
query {
  Environment {
    getDocument(docId: "...", driveId: "...")
    getDocuments(driveId: "...")
  }
}

Getting Started

Prerequisites

• Node.js 18+
• pnpm
• Powerhouse CLI (ph)

Installation

pnpm install

Development

Start the Switchboard development server:

ph switchboard --dev

This will:

• Start the local Powerhouse server
• Enable hot-reloading for editors
• Regenerate code on document model changes

Building

pnpm build

Type Checking

pnpm tsc

Linting

pnpm lint
pnpm lint:fix

Testing

pnpm test

Project Structure

@web3-berlin/powerhouse-hosting-package/
├── document-models/
│   ├── project/              # Project document model
│   │   ├── gen/              # Generated code (don't edit)
│   │   └── src/
│   │       └── reducers/     # Operation reducers
│   └── environment/          # Environment document model
│       ├── gen/              # Generated code (don't edit)
│       └── src/
│           └── reducers/     # Operation reducers
├── editors/
│   ├── project-editor/       # Project editor component
│   └── environment-editor/   # Environment editor component
├── processors/
│   ├── environment-status/   # Status change processor
│   └── powerhouse-hosting-db/# Database sync processor
├── subgraphs/
│   ├── project/              # Project GraphQL subgraph
│   └── environment/          # Environment GraphQL subgraph
└── scripts/                  # Lifecycle scripts (placeholders)

License

MIT