npm - @powerhousedao/academy - Versions diffs - 5.1.0-staging.0 → 5.1.0 - Mend

@powerhousedao/academy 5.1.0-staging.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

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

@@ -1,384 +0,0 @@
-# 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/TodoList/00-GetTheStarterCode.md DELETED Viewed

@@ -1,24 +0,0 @@
-# Step 0 - get the starter code
-Normally you would initialize a new powerhouse project by running `ph init` with your project name. But since this is a tutorial, we want to provide branches with the final code for each step.
-Just for the tutorial, please instead make a fork of [this repository](https://github.com/powerhouse-inc/todo-tutorial).
-*NOTE:* please _uncheck_ the checkbox that says "copy the main branch only" when making your fork — we want to keep the other branches for each step.
-Once you have your fork, clone it to your machine with `git clone`, the GitHub desktop app or the GitHub cli.
-The starter branch of this tutorial is: `step-1-generate-todo-list-document-model`.
-Checkout that branch, and then create your own branch from it with whatever name you want, something like `do-the-tutorial` will work nicely.
-The code at the step 1 branch of this repository is exactly the same as what you would get if you ran `ph init todo-tutorial`.
-Each step in this tutorial has two branches associated with it. One is the starting point and the other is the final code after the step is complete. They each have names like `step-1-` for the starting point and `step-1-complete-` for the complete code. You can use the starting point branches if you want to start at a later step or skip a step, and you can use the complete code to compare with your branch if you get stuck.
-To compare your branch, either do `git diff my-branch step-complete-branch` or use the "compare with branch" option in the GitHub desktop app.
-Finally, run `pnpm install` to install the project dependencies.
-Now we're ready to get started.

package/docs/academy/03-ExampleUsecases/TodoList/01-GenerateTodoListDocumentModel.md DELETED Viewed

@@ -1,211 +0,0 @@
-# Step 1 - Generate the `TodoList` document model
-## Overview
-This tutorial guides you through creating a simplified version of a 'Powerhouse project' for a **To-do List**.
-A Powerhouse project primarily consists of a document model and its editor.
-As your projects use-case expands you can add data-integrations or a specific drive-app as seen in the demo package.
-For todays purpose, you'll be using Connect, our user-centric collaboration tool and Vetra Studio, the builder tooling through which developers can access and manage specifications of your project.
-## Develop a single document model in Connect
-Once in the project directory, run the `pnpm connect` command to start a local instance of the Connect application. This allows you to start your document model specification document.
-Run the following command to start the Connect application:
-    ```bash
-    pnpm connect
-    ```
-The Connect application will start and you will see the following output:
-    ```bash
-      ➜  Local:   http://localhost:3000/
-      ➜  Network: http://192.168.5.110:3000/
-      ➜  press h + enter to show help
-    ```
-A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser. You will see your local drive and a button to create a new drive.
-:::tip
-If you local drive is not present navigate into Settings in the bottom left corner. Settings > Danger Zone > Clear Storage.
-Clear the storage of your localhost application as it might has an old session cached.
-:::
-4. Move into your local drive.
-   Create a new document model by clicking the `DocumentModel` button, found in the 'New Document' section at the bottom of the page. Name your document `Todo List`.
-If you've followed the steps correctly, you'll have an empty `TodoList` document where you can define the **'Document Specifications'**.
-## TodoList document specification
-To start, fill in the following details for your new document model:
-Name: `Todo List`
-Document type: `powerhouse/todo-list`
-Author name: Powerhouse
-Website URL: https://powerhouse.inc
-It's important that you use these exact details so that your generated code matches the generated code in the tutorial repository.
-We'll continue with this project to teach you how to create a document model specification and later an editor for your document model. We use the **GraphQL Schema Definition Language** (SDL) to define the schema for the document model.
-Below, you can see the SDL for the `TodoList` document model.
-:::info
-This schema defines the **data structure** of the document model and the types involved in its operations, which are detailed further as input types.
-Documents in Powerhouse leverage **event sourcing principles**, where every state transition is represented by an operation. GraphQL input types describe operations, ensuring that user intents are captured effectively. These operations detail the parameters needed for state transitions. The use of GraphQL aligns these transitions with explicit, validated, and reproducible commands.
-:::
-## The document model state schema
-First, let's add a graphql type that represents an individual item in a todo list document. A todo item has an ID, text, and can be either checked or unchecked.
-Add this underneath the boilerplate `TodoListState` type you see in the Global State Schema text editor.
-```graphql
-# Defines a GraphQL type for a single to-do item
-type TodoItem {
-  id: OID! # Unique identifier for each to-do item
-  text: String! # The text description of the to-do item
-  checked: Boolean! # Status of the to-do item (checked/unchecked)
-}
-```
-Now update the `TodoListState` type to use our new type by replacing the boilerplate with this:
-```graphql
-type TodoListState {
-  items: [TodoItem!]!
-}
-```
-The final result in your editor should look like this:
-```graphql
-type TodoListState {
-  items: [TodoItem!]!
-}
-# Defines a GraphQL type for a single to-do item
-type TodoItem {
-  id: OID! # Unique identifier for each to-do item
-  text: String! # The text description of the to-do item
-  checked: Boolean! # Status of the to-do item (checked/unchecked)
-}
-```
-With our state schema defined, go ahead and click the "Sync with schema" button underneath "Global State Initial Value". This will set the initial state for the documents you create with this model based on the schema you defined.
-Your initial value field should now look like this:
-```json
-{
-  "items": []
-}
-```
-## Operation inputs and their schemas
-We've defined the shape for the state of our `TodoList` documents, but we also need to be able to update them.
-Documents are updated by dispatching actions, which are applied to documents as operations.
-We define modules to group sets of operations together. In this simple case, we will only need one module.
-Add a new module for our `todos` operations by typing `todos` in the "Add new module" input and pressing enter.
-We need to add three different operations to this module:
-1. add todo item
-2. update todo item
-3. delete todo item
-Let's start with adding todos.
-When we add a new todo, the only input we need to provide is the text. Creating the ID will be handled later in our reducer code, and todos always start as unchecked by default.
-type `add todo item` in the "Add new operation" input and press enter.
-You will see your new operation with the name `ADD_TODO_ITEM` (we automatically handle changing the casing to the required CONSTANT_CASE).
-You will also see a boilerplate placeholder graphql input.
-Update the graphql input like so:
-```graphql
-input AddTodoItemInput {
-  text: String!
-}
-```
-Next let's handle updating todo items.
-Type `update todo item` in the "Add new operation" input and press enter.
-For updating items, we will need to provide an `id` so we know which one to update. We can use the same operation to update the text or the checked state, so both of these fields are optional (no ! on the field).
-Update the `UpdateTodoItemInput` to be like so:
-```graphql
-input UpdateTodoItemInput {
-  id: OID!
-  text: String
-  checked: Boolean
-}
-```
-Finally, we can handle the delete item operation.
-type `delete todo item` in the "Add new operation" input.
-For deleting items, all we need is an `id`.
-Update your `DeleteTodoItemInput` to be like this:
-```graphql
-input DeleteTodoItemInput {
-  id: OID!
-}
-```
-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 document to your local machine. Ideally, you should save your file in the root of your repository with the name `todo-list.phd`
-## Generating your document model code
-With our newly created document model, we can run the codegen to generate the rest of the code for it.
-To run the codegen, you use the `generate` command with a path to the file you just exported.
-```bash
-pnpm generate ./todo-list.phd
-```
-**NOTE:** this generated code contains values that will always be different for each generated document model, like module ids for example. For the purposes of this tutorial, we recommend that you instead use the reference example that we have already included in the repo for you — this will make your generated code look exactly the same as the generated code in the branches in the repo, and your diffs will match exactly.
-To use our reference example, run:
-```bash
-pnpm generate ./todo-list.phdm.phd
-```
-This will overwrite your generated code with code that is identical to the branches in this repository.
-## Check your work
-To make sure all works as expected, we should:
-- check types
-run: `pnpm tsc`
-- check linting
-run: `pnpm lint`
-- check tests
-run: `pnpm test`
-- make sure your code matches the code in the completed step branch
-run: `git diff your-branch-name step-1-complete-generated-todo-list-document-model`
-### Up next: reducers and operations
-Up next, you'll learn how to implement the runtime logic and components that will use the `TodoList` document model specification you've just created and exported.