@powerhousedao/academy 0.1.0-dev.0

package/docs/academy/02-AdvancedTutorial/05-Launch/02-IntroductionToPackages.md

@@ -0,0 +1,79 @@
+# Intro to Packages
+
+Packages of document models are a core structuring mechanism in the Powerhouse framework, allowing developers to group and manage related document models efficiently. These packages serve as modular collections of document definitions, ensuring consistency, scalability, and reusability across different applications.
+
+By packaging document models together, developers can create well-organized, interoperable sets of data structures that capture the specific needs of various operational processes. Whether used for financial operations, governance, or contributor management, these packages streamline development and integration within Powerhouse's decentralized framework.
+
+### Key Features
+
+- **Modular Structure** – Packages encapsulate related document models, making it easier to manage and deploy them as a cohesive unit.
+- **Standardized Definitions** – Each document model within a package follows Powerhouse's structured schema approach, ensuring consistency in data representation.
+- **Reusability and Extensibility** – Packages can be shared across different projects or extended with additional models as needed.
+- **Dependency Management** – Developers can define dependencies between document models, ensuring proper relationships and data flows between interconnected components.
+- **Automated Schema Evolution** – Versioning mechanisms allow document models within a package to evolve over time without breaking existing functionality.
+
+### Example Use Cases
+
+- **Finance Package** – A set of document models handling invoices, payments, budgets, and financial reporting. link
+- **Contributor Billing Package** – Defines document models for tracking work, invoicing, and facilitating payments (in both fiat and crypto) for contributors in decentralized organizations. link
+- **Governance Package** – Models for proposals, voting, contributor agreements, and decision-making processes. link
+- **People Ops Package** – Documents managing contributor profiles, roles, task assignments, and reputation tracking. link
+- **Project Management Package** – Models for task tracking, milestones, resource allocation, and deliverables. link  
+
+
+    A **Powerhouse Package** is a **modular unit** that defines and automates **data structures and workflows** within the Powerhouse ecosystem. Each package includes several components that work together to ensure **seamless interaction, data processing, and automation** for different areas of decentralized operations.
+
+Packages follow a **scoped naming convention** based on the organization that owns them or created the package:
+
+- `@powerhousedao` The organization behind Powerhouse.
+- `@sky-ph` The Sky / MakerDAO organization with a -ph suffix to indicate it concerns Powerhouse ecosystem packages.
+- `@myorg-ph` Your organization with the -ph suffix included.
+
+Within a package, you'll find **several key modules**, each serving a distinct role in structuring and processing data.
+
+---
+
+## **Modules of a Powerhouse Package**
+
+### **1. Document Model**
+
+The **core component** of any package, defining how data is structured and manipulated.
+
+- Specifies **schemas** (data structures) and **state transitions** (operations).
+- Serves as the foundation for decentralized workflows.
+- **Example:** An **Invoice** document model might define fields like `issuer`, `recipient`, `amount`, and operations like `ADD_LINE_ITEM` or `MARK_AS_PAID`.
+
+### **2. Document Model Editor**
+
+A **UI component** that allows users to **interact with document models visually**.
+
+- Enables users to **create, modify, and manage** documents without coding.
+- Supports multiple editors for a single document model, offering different **UI experiences** tailored to specific roles.
+
+### **3. Scripts**
+
+**Automated actions** that run on demand or on a schedule.
+
+- Executes **one-time or recurring tasks** within a package.
+- Not continuously running—activated manually or at predefined intervals.
+- **Example:** A script that **generates a weekly financial report** from invoice data.
+
+### **4. Processors**
+
+**Event-driven background tasks** that react to document changes.
+
+- Subscribes to **document operations or system events** and processes data automatically.
+- Supports real-time **data updates, analytics, and workflow automation**.
+- **Example:** A processor that **monitors new invoices** and updates an **analytics dashboard** in real-time.
+
+### **5. Drive-Apps**
+
+**Custom interfaces** that provide enhanced ways to interact with a package's document models.
+
+- Allows **visualization, sorting, and organization** of drive contents (e.g., **Kanban boards, list views**).
+- Can aggregate data and display **key insights** from document models.
+- **Example:** A Drive-App for **People Ops** might show a **dashboard of contributor profiles, role assignments, and activity logs**.
+
+---
+
+Each of these modules plays a crucial role in making **Powerhouse Packages extensible, reusable, and efficient**, allowing developers and organizations to **streamline operations and automate workflows** within decentralized environments.

package/docs/academy/02-AdvancedTutorial/05-Launch/02-PublishYourProject.md

@@ -0,0 +1,230 @@
+# Publish Your Package
+
+This tutorial is a step by step guide tackling the following topics: 
+1. the process of **building a powerhouse project** 
+2. the process of **publishing it as a package**
+
+:::info
+Let's start with some **key concepts** that will help you understand the process we're going to go through in this tutorial.
+
+- **Powerhouse Project**: The construction site of your package: A project is built with document models and editors which you will publish to NPM as a package with modules.
+- **Powerhouse Modules**: The modules that are part of your project, such as the document models, editors, processors or scripts. 
+- **Powerhouse Drive Apps**: Customized drive interfaces that function as a drive add and enhance or augment the functionality of your documents and workflows within the drive. 
+- **Powerhouse Package**: A package is a collection of modules that are published to NPM and can be installed on a server instance or locally on your machine with help of the host apps such as Connect, Switchboard & Fusion. Organizations build packages for specific purposes or workflows.
+
+![Key Concepts](images/keyconcepts.png)
+:::
+
+
+## 1. Building your project 
+
+To start building your project with it's dedicated document models and editors we'll run the following command:
+
+  ```bash
+   ph init
+   ```
+
+<details>
+<summary> Command not working? Did you install `ph-cmd`? </summary>
+
+The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. You can get access to the Powerhouse Ecosystem tools by installing them globally using:
+```bash
+pnpm install -g ph-cmd
+``` 
+
+For experimental features, use --version [version] which allows selecting a specific branch of our document-model-boilerplate. There are --dev and --staging options. Select `ph init --dev` to use the latest development version. Please be aware that this version can contain bugs and experimental features that aren't fully tested.  
+
+Key commands include:
+- `ph connect` for running the Connect application locally
+- `ph switchboard` or `ph reactor` for starting the API service
+- `ph init` to start a new project and build a document model
+- `ph help` to get an overview of all the available commands
+
+This tool will be fundamental on your journey when creating, building, and running document models
+
+</details>
+
+<details>
+<summary> Got `ph-cmd` installed, but command not working? Reset your package manager cache</summary>
+
+If you need to reset your package manager, you can run the following commands for your package manager: (pnpm, npm, yarn)
+
+```bash
+pnpm cache verify
+pnpm store prune
+pnpm cache clean --force
+
+npx clear-npx-cache
+
+npm cache verify
+npm cache clean --force
+npm cache verify
+
+yarn cache list
+yarn cache clean --force
+yarn cache list
+```
+</details>
+
+<details>
+<summary> How to make use of different branches? </summary>
+
+When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches. These branches contain more experimental features then the latest stable release the PH CLI uses by default. They can be used to get access to a bugfix or features under development.
+
+| Command | Description |
+|---------|-------------|
+| **pnpm install -g ph-cmd** | Install latest stable version |
+| **pnpm install -g ph-cmd@dev** | Install development version |
+| **pnpm install -g ph-cmd@staging** | Install staging version |
+| **ph init** | Use latest stable version of the boilerplate |
+| **ph init --dev** | Use development version of the boilerplate |
+| **ph init --staging** | Use staging version of the boilerplate |
+| **ph use** | Switch all dependencies to latest production versions |
+| **ph use dev** | Switch all dependencies to development versions |
+| **ph use prod** | Switch all dependencies to production versions |
+
+Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
+</details>
+
+### 1.1. Specifying your project details
+
+When you are creating your own project, you will be asked to name your project. 
+Which will also become the package name when someone else wants to install it in a cloud environment via npm in the future.
+
+Please feel free to navigate to the package.json file and fill in all the other available fields such as `name`, `version`, `author`, `license` and `main`.
+
+  ```bash
+{  
+"name": "@your-org-ph/package-name",  #Your organization name with the -ph suffix to indicate it's a powerhouse related organization & package. 
+"version": "1.0.0", 
+"author": "Your Name",
+"license": "AGPL-3.0-only",
+"main": "index.js"  
+}
+```
+
+Now that you've created your powerhouse project you are ready to generate the necessary directory and file structure to add your document models.
+
+```bash
+ph generate
+```
+The **generate** command will start the configuration of your powerhouse project and generates a directory with the necessary files and folders to build your project. 
+These include:
+- `document-models`: A folder containing the document models schemas you've defined in Connect Studio Mode.
+- `editors`: A folder containing the editors you've defined in react, potentially making use of the reusable components. 
+- `processors`: A folder containing the processors you might be running on your document models later on. 
+- `scripts`: A folder containing the scripts you might use.
+- `tests`: A folder containing your unit tests.
+
+### 1.2. Adding Document Models, editors and unit tests
+
+Now that you've set up your directory. 
+Go ahead and add the document models you'd like to add by going through the standard document model building flow:
+
+:::info
+These steps are explained more in depth in any of our tutorials. Follow along with one of the tutorials that matches your project the most.
+:::
+
+1. Defining your Document Model **GraphQL Schema** in the document model document editor by launching the document model editor in Connect Studio Mode with the `ph connect` command.
+2. Defining your Document Model **Operations** in the document model document operations editor and their graphQL counterparts.
+3. Generating the scaffolding code by **exporting** the Zip file from connect and **importing** it into your project. (Save it in the directory you've created in the previous step) Run `ph generate <zipfile>`.
+4. Implementing the **reducer code** and unit tests of your document models reducers.
+5. Implementing the **document editors** to visualize and interact with your document models.
+6. Run **unit tests** and verify the editor functionality via `ph connect` for local testing.
+7. Add a **manifest file** to your project and updating your index.js file to export your modules.
+
+### 1.3. Verifying your project
+Now that we've completed our directory with the reducers, tests and editors, and your project is populated with modules we'll verify the build output and see if everything is working correctly. 
+
+Let's **verify the package build output** with the following command:
+```bash
+pnpm build
+```
+
+This command will **build** the project and create a build directory with the output. The code gets optimized and minified. It optimizes the code for production and distribution so different environments can use it as a package.
+
+This command will **start a local server** and serve the build output.
+Inspect the build output and verify that the document models are working correctly.
+
+```bash
+pnpm serve (Not working yet)
+```
+
+### 1.4 Storing your project in a git repository
+
+Now that you've verified your project is working correctly, you can store your project in a git repository.
+Why? 
+- So you can track the changes of your project in a remote repository and benefit from the collaboration features of git.
+- So you can publish your project to the npm registry and install it on a server instance or locally on your machine.
+
+If you stick to the layout generated by the `ph init` command, where its folders for document models and editors, you should later be able to install your package with `ph install @<your-org/package-name>` once it's published to the npm registry.
+
+```bash
+git init
+git add .
+git commit -m "Initial commit"
+```
+
+This will initialize a git repository and add all the files to the repository.
+
+## 2. Publishing your project
+
+For this step you'll need to register your organization on npm.
+If you haven't already registered your organization on npm, you can do so by running the following command:
+```bash
+pnpm adduser
+```
+Create an organization on [NPM](https://www.npmjs.com/) using the naming convention: `@yourorganization-ph`
+   - The `-ph` suffix indicates its a Powerhouse ecosystem package to help you and others identify it from regular NPM packages. 
+   - Example: `@acme-ph`
+
+To make sure you can differentiate between Powerhouse ecosystem packages and other packages we recommend setting up a separate npm account for your organization with the -ph suffix. **example: @yourorg-ph**
+We advise you to **use a dedicated npm account for your organization and not your personal account**.
+
+Once you've registered your organization on npm, you can now publish your project to the npm registry. 
+Log in via the command line:
+```bash
+npm login
+```
+You'll be prompted for your username, password, and email in a separate browser window. 
+
+Once you've logged in, you can configure your package.json for npm before publishing. 
+If you're publishing a package under a scope (like @your-org/my-package), you might need to add the `publishConfig` to ensure it's public, otherwise scoped packages default to private:
+
+```json
+{
+  "name": "@your-org/my-package",
+  "version": "1.0.0",
+  "main": "index.js",
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+For the actual publishing step, run the following command to publish your project to the npm registry:
+```bash
+npm publish
+```
+
+Optionally, if you are publishing a scoped package and you want it public, run:
+```bash
+npm publish --access public
+```
+
+Now let's verify that the package(s) get published in the package repository, next to pre-existing packages that you might have been publishing before.
+
+## 3. Deploying the host apps & project.
+Now that we've installed all the necessary services on our server instance, we can start deploying the host apps & our packaged project from npm.
+
+Install your project package we've published earlier on your local connect (`ph connect`) instance by running the following command:
+
+```bash
+ph install @<your-org/package-name>
+```
+Alternatively you can also install the package in the settings of Connect in the 'package manager' section. (Not available yet)
+Where you'll be able to use the same package name as you've used in the `package.json` file and install it at the click of a button.
+
+![package manager](images/homedesign.png)
+
+Got this far? Congratulations on publishing your first package! 

package/docs/academy/02-AdvancedTutorial/05-Launch/03-RunOnACloudServer.md

@@ -0,0 +1,279 @@
+# Run it on a EC2 instance
+
+## Tutorial Workflow
+
+This tutorial guides you through the process of deploying your Powerhouse project on a cloud server.
+
+To help you navigate the steps involved, the diagram below illustrates the overall workflow. It shows the different environments and actions we'll cover.
+
+![tutorial schema](images/tutorialschema.png)
+
+Understanding this process is key because, within the Powerhouse ecosystem, users typically start by installing pre-built packages onto their Connect or Switchboard instances. These packages are often sourced from a central repository, similar to an app store. In the previous tutorial, we have [created and published our package](/docs/academy/AdvancedTutorial/Launch/PublishYourProject) on the Node Package Manager (NPM) registry as our "app store", and now you'll learn how to deploy your own package to a cloud environment.
+
+## 1. Setting up your cloud environment
+### 1.1. Launching your server instance (AWS \- EC2 \- Ubuntu)
+
+Let's have a look at how to set up Connect & Switchboard apps on a cloud server.
+Ask your IT provider to get access to the AWS environment to set up a server.
+Launch a new server instance for Connect and Switchboard with the specific specs that fit your project.
+
+The steps to create an EC2 instance:
+   - Make sure your region is set to eu-west-1 (Ireland)
+   - Name your instance something like `cloud-server` or your project's name
+   - Select Ubuntu 24.04 LTS
+   - Architecture 64-bit (x86)
+   - Scroll down to Instance type and select t2.medium (recommended)
+      - 2 vCPUs and 4 GiB of memory are the recommended minimum specs
+      - For larger projects or higher load, consider t2.large or t2.xlarge
+   - Create a new key pair and save it in a secure location from which you can connect to your instance with the SSH client later.
+   - Configure the security group to allow inbound traffic:
+      - SSH (Port 22) from your IP address
+      - HTTP (Port 80) from anywhere
+      - HTTPS (Port 443) from anywhere
+      - Custom TCP (Port 8442) for Connect
+      - Custom TCP (Port 8441) for Switchboard
+   - **Launch the instance**
+
+Now click on your instance ID, which will open a new window with the instance details. Hit the 'Connect' button to get the connection details.
+Within the instance details, you'll find the public IP address of your server instance. We'll use this to connect to our server instance later.
+
+:::warning
+Make sure to keep your key pair file (.pem) secure and never share it. Without it, you won't be able to access your instance. Also, consider setting up AWS IAM roles and policies for better security management.
+:::
+
+### 1.2. Setting up your SSH connection
+
+Once you've generated your key pairs and added them to the designated folder, you can set up the SSH connections to start the process.
+
+SSH, which stands for **Secure Shell**, is a cryptographic network protocol used to securely access and manage devices over an unsecured network. It provides a secure channel over an unsecured network by using encryption, ensuring that data transmitted between your computer and the server remains confidential and tamper-proof.
+
+To establish an SSH connection, you'll typically use an SSH client. On Unix-like systems (Linux, macOS), the SSH client is usually pre-installed.
+Follow the instructions for the AWS instance you've configured with Ubuntu and set up your connection by adding the necessary commands in your terminal.
+
+![Setting up your SSH connection](images/SSHConnection.png)
+
+Your Ubuntu instance is usually always a little out of date. So use the following commands to get it up to speed.
+
+   ```bash
+   sudo apt update && sudo apt upgrade
+   ```
+
+### 1.3. Installing the required software with a script
+
+Now that we've connected to our Ubuntu instance, we'll need to install the necessary services on our server to get things going, such as NVM, Node, NPM, etc.
+
+For this, our team has set up a small script that will help you to automate a series of installations.
+
+Enter the base command, which will start installing the necessary services on your server by downloading the install script and running it directly in the bash shell for execution.
+
+   ```bash
+   curl -o- https://raw.githubusercontent.com/powerhouse-inc/powerhouse/refs/heads/main/clis/ph-cli/scripts/setup.sh | bash
+   ```
+
+The script contains the following commands and will help you set up a series of services on your server.
+
+- **NVM**: Node Version Manager for managing node.js 22 versions
+- **node.js 22**: JavaScript runtime
+- **PM2**: Process manager for node.js 22 applications
+- **ph-cmd**: Powerhouse CLI tool for managing projects.
+- **pnpm**: Fast, disk-space-efficient package manager
+
+:::info
+ph-cmd is a tool that helps you manage your Powerhouse projects. It's a command-line interface package that you can install globally on your server and personal machine. It gives you access to a series of powerful commands to create or manage your projects, start or stop your services, install your project on a server instance, etc. Visit this page to learn more about the [Powerhouse builder tooling](/docs/academy/AdvancedTutorial/Create/BuilderTools)
+
+<details>
+<summary> How to make use of different branches? </summary>
+
+When installing or using the Powerhouse CLI commands you are able to make use of the dev & staging branches. These branches contain more experimental features then the latest stable release the PH CLI uses by default. They can be used to get access to a bugfix or features under development.
+
+| Command | Description |
+|---------|-------------|
+| **pnpm install -g ph-cmd** | Install latest stable version |
+| **pnpm install -g ph-cmd@dev** | Install development version |
+| **pnpm install -g ph-cmd@staging** | Install staging version |
+| **ph init** | Use latest stable version of the boilerplate |
+| **ph init --dev** | Use development version of the boilerplate |
+| **ph init --staging** | Use staging version of the boilerplate |
+| **ph use** | Switch all dependencies to latest production versions |
+| **ph use dev** | Switch all dependencies to development versions |
+| **ph use prod** | Switch all dependencies to production versions |
+
+Please be aware that these versions can contain bugs and experimental features that aren't fully tested.
+</details>
+
+:::
+
+Let's have a look at the other commands that are part of the script that will help you install the necessary services on your server.
+
+   #### 1. Load NVM into the current shell session
+   ```bash
+   export NVM_DIR="$HOME/.nvm"
+   [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  
+   ```
+
+   #### 2. Checks if the file nvm.sh exists and loads it if the condition is true.
+   ```bash
+   [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  
+   ```
+   #### 3. Loading & Verifying NVM
+   ```bash
+   nvm --version
+   ```
+
+   #### 4. Install node.js 22 by using NVM
+   ```bash
+   nvm install 22
+   ```
+
+   #### 5. Install pnpm package manager globally
+   ```bash
+    nvm install 22
+   pnpm setup
+   source $HOME/.bashrc
+   ```
+   Now follow the instructions of your Ubuntu server at the end of the installation.
+
+   #### 6. Install Powerhouse CLI 'globally' using pnpm, making it available for command-line use anywhere. This makes it available for command-line use anywhere, not just locally within the project directory.
+
+   ```bash
+   pnpm install -g ph-cmd
+   ```
+
+## 2. Deploying the host apps & project. 
+
+Now that we've installed all the necessary services on our server instance, we can start deploying the host apps & our packaged project from npm.
+
+1. **Install your project package** that we published earlier on npm, onto the server instance.
+	   ```bash
+	   ph install @your-org/package-name
+	   ```
+
+2. **Start the Connect service** so that we can start interacting with our project.
+	```bash
+	ph connect --https --port 8442
+	```
+	Let's verify that the Connect service is running. Since we can't make use of localhost and we're running the Connect service on the server instance, we'll need to use the public IP address of our server instance to start interacting with our project. Copy the public IP address of your server instance and paste it into your browser. Now add the port `:8442` to the end of the URL and you should see your project running.
+
+   Create a new document and start interacting with it. Add a new item to the list so you can query the document through the GraphQL playground in Switchboard in the next step.
+
+3. **Start the Switchboard service** and run the following command to boot the Reactor.
+	```bash
+	ph switchboard --port 8441
+	```
+	Let's verify that the Reactor has detected your project and is ready to start by navigating to the GraphQL playground.
+   Since we can't make use of localhost and we're running the Switchboard service on the server instance, we'll need to use the public IP address of our server instance to start interacting with our project. Copy the public IP address of your server instance and paste it into your browser. Now add the port `:8441` to the end of the URL and you should get access to the GraphQL playground.
+
+
+## 3. Setup the host apps as system services
+
+Now that we've installed the host apps and our project on the server instance, we'll configure them to run as system services. This ensures that:
+- Services automatically start when the server boots up
+- Services automatically restart if they crash
+- Services continue running after you log out of SSH
+- System resources are properly managed through PM2
+
+### 3.1. Register services for automatic startup
+
+Use the following command to register both Connect and Switchboard as system services:
+
+```bash
+ph service startup
+```
+
+To remove the services from automatic startup:
+
+```bash
+ph service unstartup
+```
+<details>
+<summary>Read the ph service --help command</summary>
+
+Usage: ph service [options] `<action>` [service]
+
+Manage services
+
+
+Command Overview:
+  The service command manages Powerhouse services, allowing you to start, stop, check status,
+  and more. It provides a centralized way to control the lifecycle of services in your project.
+
+  This command:
+  1. Controls service lifecycle (start, stop, status, etc.)
+  2. Manages multiple services from a single interface
+  3. Provides detailed information about running services
+  4. Uses PM2 under the hood for process management
+
+Arguments:
+  `<action>`              The action to perform. Available actions:
+                        - start: Launch the specified service
+                        - stop: Terminate the specified service
+                        - status: Check the current status of services
+                        - list: List all managed services (default)
+                        - startup: Configure services to start on system boot
+                        - unstartup: Remove services from system startup
+                        
+  [service]             Optional. The service to act upon. Available services:
+                        - switchboard: The document processing engine
+                        - connect: The Connect Studio interface
+                        - all: Act on all services (default)
+
+Examples:
+  $ ph service                               # List all services (same as 'ph service list all')   
+  $ ph service start switchboard             # Start the Switchboard service   
+  $ ph service stop connect                  # Stop the Connect service   
+  $ ph service start all                     # Start all services   
+  $ ph service status                        # Check status of all services   
+  $ ph service startup                       # Configure services to start on system boot   
+  $ ph service unstartup                     # Remove services from system startup   
+
+Notes:
+  - Services are managed using PM2, a process manager for node.js 22 applications
+  - The 'status' action shows uptime, memory usage, CPU usage, and other metrics
+  - The 'list' action is the default when no action is specified
+  - The 'all' service is the default when no service is specified
+
+  </details>
+
+### 3.2. Managing individual services
+
+You can control each service independently:
+
+```bash
+# Start individual services
+ph service start connect     # Starts only Connect
+ph service start switchboard # Starts only Switchboard
+
+# Stop individual services
+ph service stop connect      # Stops only Connect
+ph service stop switchboard  # Stops only Switchboard
+```
+
+### 3.3. Managing all services together
+
+To control both services at once:
+
+```bash
+ph service start  # Starts both Connect and Switchboard
+ph service stop   # Stops both Connect and Switchboard
+```
+
+:::tip
+You can check the status of your services at any time using:
+```bash
+ph service status
+```
+This will show you if services are running, their uptime, and resource usage.
+:::
+
+:::warning
+After making any configuration changes to your project, remember to restart the affected services for the changes to take effect.
+:::
+
+## 4. Verify your project is running on your server
+
+- Open the server domain in your browser, and you should see your project running.
+- Verify that synchronization is working and your document is available.
+- Try to make a change to your document and see if it's reflected in another instance with that same document.
+- Query the document through the GraphQL playground.
+
+Congratulations! You've now published your project and are ready to start collaborating with your team on the same document models and editors!