@powerhousedao/academy 5.1.0-dev.9 → 5.1.0-staging.0

package/docs/academy/02-MasteryTrack/05-Launch/05-DockerDeployment.md

@@ -0,0 +1,384 @@
+# Docker Deployment Guide
+
+## Introduction
+
+Powerhouse provides official Docker images for deploying your applications in containerized environments. This guide covers the available Docker images, how to use them with Docker Compose, and the environment variables you can configure.
+
+Docker deployment is ideal for:
+- **Production environments** that require consistent, reproducible deployments
+- **Development teams** that want to share a common environment
+- **CI/CD pipelines** that need automated testing and deployment
+- **Cloud platforms** like AWS ECS, Google Cloud Run, or Kubernetes
+
+## Available Docker Images
+
+Powerhouse publishes three official Docker images to the GitHub Container Registry (ghcr.io):
+
+### 1. Connect
+
+The Connect image provides the Powerhouse web application frontend with an embedded Nginx server.
+
+```
+ghcr.io/powerhouse-inc/powerhouse/connect
+```
+
+**Available tags:**
+- `latest` - Latest stable release
+- `dev` - Development builds
+- `staging` - Staging builds
+- `vX.Y.Z` - Specific version tags (e.g., `v1.0.0`)
+
+### 2. Switchboard
+
+The Switchboard image provides the backend API server that handles document synchronization and GraphQL endpoints.
+
+```
+ghcr.io/powerhouse-inc/powerhouse/switchboard
+```
+
+**Available tags:**
+- `latest` - Latest stable release
+- `dev` - Development builds
+- `staging` - Staging builds
+- `vX.Y.Z` - Specific version tags (e.g., `v1.0.0`)
+
+### 3. Academy
+
+The Academy image provides the documentation website.
+
+```
+ghcr.io/powerhouse-inc/powerhouse/academy
+```
+
+**Available tags:**
+- `latest` - Latest stable release
+- `dev` - Development builds
+- `staging` - Staging builds
+- `vX.Y.Z` - Specific version tags (e.g., `v1.0.0`)
+
+## Quick Start with Docker Compose
+
+The easiest way to run Powerhouse locally is using Docker Compose. Create a `docker-compose.yml` file or use the one provided in the repository:
+
+```yaml
+name: powerhouse
+
+services:
+  connect:
+    image: ghcr.io/powerhouse-inc/powerhouse/connect:dev
+    environment:
+      - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres
+      - BASE_PATH=/
+    ports:
+      - "127.0.0.1:3000:4000"
+    networks:
+      - powerhouse_network
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  switchboard:
+    image: ghcr.io/powerhouse-inc/powerhouse/switchboard:dev
+    environment:
+      - DATABASE_URL=postgres://postgres:postgres@postgres:5432/postgres
+    ports:
+      - "127.0.0.1:4000:4001"
+    networks:
+      - powerhouse_network
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:16.1
+    ports:
+      - "127.0.0.1:5444:5432"
+    environment:
+      - POSTGRES_PASSWORD=postgres
+      - POSTGRES_DB=postgres
+      - POSTGRES_USER=postgres
+    networks:
+      - powerhouse_network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 3
+
+networks:
+  powerhouse_network:
+    name: powerhouse_network
+```
+
+### Running the Stack
+
+Start all services:
+
+```bash
+docker compose up -d
+```
+
+View logs:
+
+```bash
+docker compose logs -f
+```
+
+Stop all services:
+
+```bash
+docker compose down
+```
+
+After starting, you can access:
+- **Connect**: http://localhost:3000
+- **Switchboard**: http://localhost:4000
+
+## Environment Variables
+
+### Connect Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Port the server listens on | `4000` |
+| `PH_CONNECT_BASE_PATH` | Base URL path for the application | `/` |
+| `PH_PACKAGES` | Comma-separated list of packages to install at startup | `""` |
+| `PH_CONNECT_SENTRY_DSN` | Sentry DSN for error tracking | `""` |
+| `PH_CONNECT_SENTRY_ENV` | Sentry environment name | `""` |
+| `DATABASE_URL` | PostgreSQL connection string | Required |
+
+#### Feature Flags
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PH_CONNECT_DEFAULT_DRIVES_URL` | Default drives URL to load | `""` |
+| `PH_CONNECT_ENABLED_EDITORS` | Enabled editor types (`*` for all) | `"*"` |
+| `PH_CONNECT_DISABLED_EDITORS` | Disabled editor types | `""` |
+| `PH_CONNECT_PUBLIC_DRIVES_ENABLED` | Enable public drives | `"true"` |
+| `PH_CONNECT_CLOUD_DRIVES_ENABLED` | Enable cloud drives | `"true"` |
+| `PH_CONNECT_LOCAL_DRIVES_ENABLED` | Enable local drives | `"true"` |
+| `PH_CONNECT_SEARCH_BAR_ENABLED` | Enable search bar | `"false"` |
+| `PH_CONNECT_DISABLE_ADD_PUBLIC_DRIVES` | Disable adding public drives | `"false"` |
+| `PH_CONNECT_DISABLE_ADD_CLOUD_DRIVES` | Disable adding cloud drives | `"false"` |
+| `PH_CONNECT_DISABLE_ADD_LOCAL_DRIVES` | Disable adding local drives | `"false"` |
+| `PH_CONNECT_DISABLE_DELETE_PUBLIC_DRIVES` | Disable deleting public drives | `"false"` |
+| `PH_CONNECT_DISABLE_DELETE_CLOUD_DRIVES` | Disable deleting cloud drives | `"false"` |
+| `PH_CONNECT_DISABLE_DELETE_LOCAL_DRIVES` | Disable deleting local drives | `"false"` |
+| `PH_CONNECT_HIDE_DOCUMENT_MODEL_SELECTION_SETTINGS` | Hide document model selection | `"true"` |
+
+#### Renown Authentication
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PH_CONNECT_RENOWN_URL` | Renown authentication service URL | `"https://auth.renown.id"` |
+| `PH_CONNECT_RENOWN_NETWORK_ID` | Renown network identifier | `"eip155"` |
+| `PH_CONNECT_RENOWN_CHAIN_ID` | Renown chain ID | `1` |
+
+### Switchboard Environment Variables
+
+#### Core Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Port the server listens on | `4001` |
+| `PH_SWITCHBOARD_PORT` | Alias for PORT | `$PORT` |
+| `DATABASE_URL` | PostgreSQL or SQLite connection string | `"dev.db"` |
+| `PH_SWITCHBOARD_DATABASE_URL` | Alias for DATABASE_URL | `"dev.db"` |
+| `BASE_PATH` | Base URL path for the API | `"/"` |
+| `PH_PACKAGES` | Comma-separated list of packages to install at startup | `""` |
+
+#### Authentication
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AUTH_ENABLED` | Enable authentication | `"false"` |
+| `ADMINS` | Comma-separated list of admin wallet addresses | `""` |
+| `USERS` | Comma-separated list of user wallet addresses | `""` |
+| `GUESTS` | Comma-separated list of guest wallet addresses | `""` |
+| `FREE_ENTRY` | Allow unauthenticated access when auth is enabled | `"false"` |
+
+#### Error Tracking & Monitoring
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SENTRY_DSN` | Sentry DSN for error tracking | `""` |
+| `SENTRY_ENV` | Sentry environment name (e.g., "production", "staging") | `""` |
+| `PYROSCOPE_SERVER_ADDRESS` | Pyroscope server address for performance profiling | `""` |
+
+## Installing Custom Packages
+
+Both Connect and Switchboard support installing custom Powerhouse packages at container startup using the `PH_PACKAGES` environment variable.
+
+```yaml
+services:
+  connect:
+    image: ghcr.io/powerhouse-inc/powerhouse/connect:dev
+    environment:
+      - PH_PACKAGES=@powerhousedao/todo-demo-package,@powerhousedao/another-package
+```
+
+Packages are installed using the `ph install` command before the service starts.
+
+## Image Architecture
+
+### Connect Image
+
+The Connect image is based on Alpine Linux and includes:
+- Node.js and pnpm
+- Nginx with Brotli compression
+- The `ph-cmd` CLI tool
+- A pre-initialized Powerhouse project
+
+At startup, the entrypoint script:
+1. Installs any packages specified in `PH_PACKAGES`
+2. Builds the Connect frontend with `ph connect build`
+3. Configures and starts Nginx to serve the built files
+
+### Switchboard Image
+
+The Switchboard image is based on Node.js 22 and includes:
+- pnpm package manager
+- The `ph-cmd` CLI tool
+- Prisma CLI for database migrations
+- A pre-initialized Powerhouse project
+
+At startup, the entrypoint script:
+1. Installs any packages specified in `PH_PACKAGES`
+2. Runs Prisma database migrations (if using PostgreSQL)
+3. Starts the Switchboard server with `ph switchboard`
+
+## Production Considerations
+
+### Using Specific Version Tags
+
+For production deployments, always use specific version tags instead of `latest` or `dev`:
+
+```yaml
+services:
+  connect:
+    image: ghcr.io/powerhouse-inc/powerhouse/connect:v1.0.0
+  switchboard:
+    image: ghcr.io/powerhouse-inc/powerhouse/switchboard:v1.0.0
+```
+
+### Database Persistence
+
+For production, ensure your PostgreSQL data is persisted using volumes:
+
+```yaml
+services:
+  postgres:
+    image: postgres:16.1
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_PASSWORD=your-secure-password
+      - POSTGRES_DB=powerhouse
+      - POSTGRES_USER=powerhouse
+
+volumes:
+  postgres_data:
+```
+
+### Health Checks
+
+The provided docker-compose.yml includes health checks for PostgreSQL. Services wait for the database to be healthy before starting, preventing connection errors during startup.
+
+### Network Security
+
+The example configuration binds ports to `127.0.0.1` only:
+
+```yaml
+ports:
+  - "127.0.0.1:3000:4000"
+```
+
+This prevents direct external access. In production, use a reverse proxy (like Nginx or Traefik) to:
+- Terminate SSL/TLS
+- Handle load balancing
+- Provide additional security headers
+
+### Environment File
+
+For better security, use a `.env` file instead of hardcoding credentials:
+
+```bash
+# .env
+POSTGRES_PASSWORD=your-secure-password
+DATABASE_URL=postgres://powerhouse:your-secure-password@postgres:5432/powerhouse
+```
+
+```yaml
+services:
+  switchboard:
+    image: ghcr.io/powerhouse-inc/powerhouse/switchboard:latest
+    env_file:
+      - .env
+```
+
+## Troubleshooting
+
+### Container Won't Start
+
+Check the logs for errors:
+
+```bash
+docker compose logs connect
+docker compose logs switchboard
+```
+
+### Database Connection Issues
+
+Ensure the database is ready before services start:
+
+```bash
+docker compose logs postgres
+```
+
+Verify the `DATABASE_URL` format:
+```
+postgres://user:password@host:port/database
+```
+
+### Package Installation Fails
+
+If custom packages fail to install, check:
+1. Package name is correct
+2. Network connectivity from container
+3. Container has access to npm registry
+
+### Permission Issues
+
+If you encounter permission issues with volumes:
+
+```bash
+# Fix ownership
+sudo chown -R 1000:1000 ./data
+```
+
+## Building Custom Images
+
+You can extend the official images for custom deployments:
+
+```dockerfile
+FROM ghcr.io/powerhouse-inc/powerhouse/connect:latest
+
+# Install additional packages at build time
+RUN ph install @powerhousedao/my-custom-package
+
+# Add custom configuration
+COPY my-nginx.conf /etc/nginx/nginx.conf.template
+```
+
+Build and push your custom image:
+
+```bash
+docker build -t my-registry/my-connect:latest .
+docker push my-registry/my-connect:latest
+```
+
+## Next Steps
+
+- Learn about [Environment Configuration](./04-ConfigureEnvironment.md) for more detailed setup options
+- Explore [Publishing Your Project](./02-PublishYourProject.md) to create your own packages
+- Check the [Setup Environment Guide](./03-SetupEnvironment.md) for VM-based deployments

package/docs/academy/03-ExampleUsecases/Chatroom/03-DefineChatroomDocumentModel.md

@@ -62,47 +62,6 @@ This schema defines the **data structure** of the document model and the types i
 <summary>State schema of our ChatRoom</summary>
 
 ```graphql
-# The state of our ChatRoom
-type ChatRoomState {
-  id: OID!              # Unique identifier for the chat-room
-  name: String!         # Name of the chat-room
-  description: String   # Optional description of the chat-room
-  createdAt: DateTime!  # Timestamp of when the chat-room was created
-  createdBy: ID!        # Agent ID of the user who created the chat-room
-  messages: [Message!]! # List of messages in the chat-room
-}
-
-# A single message in the chat-room
-type Message {
-  id: OID!              # Unique identifier for the message
-  sender: Sender!       # Agent details of the message sender
-  content: String       # Message content
-  sentAt: DateTime!     # Timestamp of when the message was sent
-  reactions: [Reaction!] # Reactions to the message
-}
-
-# The sender of a message
-type Sender {
-  id: ID!               # Unique identifier for the sender
-  name: String
-  avatarUrl: URL        # Allows us to pull the ENS and/or NFT of the person's profile
-}
-
-# A reaction to a message
-type Reaction {
-  type: ReactionType!   # Type of reaction (one of the predefined emoji)
-  reactedBy: [ID!]!     # Agent IDs of users who reacted
-}
-
-# The predefined emoji reactions
-enum ReactionType {
-  THUMBS_UP
-  THUMBS_DOWN
-  LAUGH
-  HEART
-  CRY
-}
-
 type ChatRoomState {
   id: OID!
   name: String!
@@ -138,9 +97,15 @@ enum ReactionType {
   HEART
   CRY
 }
+```
+
+</details>
 
-# messages
+<details>
+<summary>Messages Module: Operations for ChatRoom Messages</summary>
 
+```graphql
+# Add a new message to the chat-room
 input AddMessageInput {
   messageId: OID!
   sender: SenderInput!
@@ -148,77 +113,34 @@ input AddMessageInput {
   sentAt: DateTime!
 }
 
+# Sender information for a message
 input SenderInput {
   id: ID!
   name: String
   avatarUrl: URL
 }
 
+# Add an emoji reaction to a message
 input AddEmojiReactionInput {
   messageId: OID!
   reactedBy: ID!
   type: ReactionType!
 }
 
+# Remove an emoji reaction from a message
 input RemoveEmojiReactionInput {
   messageId: OID!
   senderId: ID!
   type: ReactionType!
 }
-
-# settings
-
-input EditChatNameInput {
-  name: String
-}
-
-input EditChatDescriptionInput {
-  description: String
-}
 ```
 
 </details>
 
 <details>
-<summary>Messages Module: Operations schema of our ChatRoom Messages</summary>
+<summary>Settings Module: Operations for ChatRoom Settings</summary>
 
 ```graphql
-# Add a new message to the chat-room
-input AddMessageInput {
-  messageId: OID!       # ID of the message being added
-  sender: SenderInput!  # Sender information
-  content: String!      # Content of the message
-  sentAt: DateTime!     # Timestamp when the message was sent
-}
-
-# Sender information for a message
-input SenderInput {
-  id: ID!               # Unique identifier for the sender
-  name: String
-  avatarUrl: URL        # Avatar URL for the sender
-}
-
-# Add an emoji reaction to a message
-input AddEmojiReactionInput {
-  messageId: OID!       # ID of the message to react to
-  reactedBy: ID!        # ID of the user adding the reaction
-  type: ReactionType!   # Type of the reaction (emoji)
-}
-
-# Remove an emoji reaction from a message
-input RemoveEmojiReactionInput {
-  messageId: OID!       # ID of the message to remove reaction from
-  senderId: ID!         # ID of the user removing the reaction
-  type: ReactionType!   # Type of the reaction (emoji)
-}
-
-
-</details>
-
-
-<details>
-<summary>Settings Module: Operations schema of our ChatRoom Settings</summary>
-
 # Edit the chat-room name
 input EditChatNameInput {
   name: String
@@ -260,11 +182,11 @@ To define the document model, you need to open the document model editor in Conn
     }
    ```
 
-5. Below the editor, find the input field `Add module`. Create and name a module for organizing your input operations. Name the module `general_operations`. Press enter.
+5. Below the editor, find the input field `Add module`. Create the first module for message-related operations. Name the module `messages`. Press enter.
 
 6. Now there is a new field, called `Add operation`. Here you will add each input operation to the module, one by one.
 
-7. Inside the `Add operation` field, type `ADD_MESSAGE` and press enter. A small editor will appear underneath with an empty input type that you need to fill. Copy the `AddMessageInput` and `SenderInput` from the **Operations Schema** section and paste them in the editor:
+7. Inside the `Add operation` field, type `ADD_MESSAGE` and press enter. A small editor will appear underneath with an empty input type that you need to fill. Copy the `AddMessageInput` and `SenderInput` from the **Messages Module** section and paste them in the editor:
 
    ```graphql
    input AddMessageInput {
@@ -281,11 +203,15 @@ To define the document model, you need to open the document model editor in Conn
    }
    ```
 
-8. Repeat step 7 for the other input operations: `ADD_EMOJI_REACTION`, `REMOVE_EMOJI_REACTION`, `EDIT_CHAT_NAME`, and `EDIT_CHAT_DESCRIPTION`. Note that you only need to add the operation name (e.g., `ADD_EMOJI_REACTION`) without the `Input` suffix—it will be generated automatically.
+8. Add the remaining message operations to the `messages` module: `ADD_EMOJI_REACTION` and `REMOVE_EMOJI_REACTION`. Note that you only need to add the operation name (e.g., `ADD_EMOJI_REACTION`) without the `Input` suffix—it will be generated automatically.
+
+9. Add reducer exceptions to the `ADD_MESSAGE` operation for validation: `MessageContentCannotBeEmpty` and `MessageNotFound`. These will be used later to validate messages.
+
+10. Create a second module called `settings` for the chat room configuration operations.
 
-9. Add reducer exceptions to the `ADD_MESSAGE` operation for validation: `MessageContentCannotBeEmpty` and `MessageContentExceedsTheMaximumLength`. These will be used later to validate messages.
+11. Add the settings operations to the `settings` module: `EDIT_CHAT_NAME` and `EDIT_CHAT_DESCRIPTION`.
 
-10. Once you have added all the input operations, click the `Export` button at the top right of the editor to save the document model specification to your local machine. Save the file in the root of your Powerhouse project.
+12. Once you have added all the input operations, click the `Export` button at the top right of the editor to save the document model specification to your local machine. Save the file in the root of your Powerhouse project.
 
 Check the screenshot below to verify the complete implementation:
 
@@ -302,13 +228,24 @@ document-models/chat-room/
 │   ├── creators.ts                   # Action creator functions
 │   ├── types.ts                      # TypeScript type definitions
 │   ├── reducer.ts
-│   └── general-operations/
-│       └── operations.ts             # Operation type definitions
+│   ├── messages/                     # Messages module
+│   │   ├── actions.ts
+│   │   ├── creators.ts
+│   │   ├── error.ts                  # Error classes for validation
+│   │   └── operations.ts
+│   └── settings/                     # Settings module
+│       ├── actions.ts
+│       ├── creators.ts
+│       ├── error.ts
+│       └── operations.ts
 ├── src/                              # Your custom implementation
 │   ├── reducers/
-│   │   └── general-operations.ts     # Reducer functions (to implement next)
+│   │   ├── messages.ts               # Message operation reducers
+│   │   └── settings.ts               # Settings operation reducers
 │   └── tests/
-│       └── general-operations.test.ts # Test file scaffolding
+│       ├── document-model.test.ts    # Document model tests
+│       ├── messages.test.ts          # Messages operation tests
+│       └── settings.test.ts          # Settings operation tests
 ├── chat-room.json                    # Document model specification
 └── schema.graphql                    # GraphQL schema
 ```