Build dependencies

Author: rrnewton

DEPENDENCIES.md

@@ -0,0 +1,93 @@
+# Dependencies
+
+This document lists all system and package dependencies required to run the Happy self-hosted stack.
+
+## System Dependencies
+
+These must be installed on the host system:
+
+### Required
+- **Node.js 24+** - Runtime for all JavaScript/TypeScript code
+- **Yarn 1.22.22+** - Package manager (specified in package.json)
+- **PostgreSQL 17+** - Primary database
+- **Redis 7+** - Caching and pub/sub
+- **MinIO** - S3-compatible object storage
+
+### Optional
+- **FFmpeg** - Required by happy-server for media processing
+- **Python3** - Required by happy-server for some operations
+
+## Installation Commands
+
+### Ubuntu/Debian
+```bash
+# Node.js 24
+curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Yarn
+npm install -g yarn
+
+# PostgreSQL 17
+sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
+wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
+sudo apt-get update
+sudo apt-get install -y postgresql-17
+
+# Redis
+sudo apt-get install -y redis-server
+
+# MinIO
+wget https://dl.min.io/server/minio/release/linux-amd64/minio
+chmod +x minio
+sudo mv minio /usr/local/bin/
+wget https://dl.min.io/client/mc/release/linux-amd64/mc
+chmod +x mc
+sudo mv mc /usr/local/bin/
+
+# Optional: FFmpeg and Python3
+sudo apt-get install -y ffmpeg python3
+```
+
+## Package Dependencies
+
+After installing system dependencies, install package dependencies:
+
+```bash
+make install
+```
+
+This runs `yarn install` in each submodule:
+- `happy-cli/` - Installs CLI dependencies including:
+  - `tsx` - TypeScript executor (devDependency)
+  - `shx` - Cross-platform shell commands (devDependency)
+  - `pkgroll` - Package bundler (devDependency)
+  - And all production dependencies
+
+- `happy-server/` - Installs server dependencies including:
+  - `tsx` - TypeScript executor (production dependency)
+  - Prisma ORM and other server dependencies
+
+- `happy/` - Installs webapp dependencies (Expo/React Native)
+
+## Dependency Check
+
+The `happy-launcher.sh` script automatically checks for installed package dependencies before starting services. If you see this error:
+
+```
+[ERROR] Dependencies not installed in happy-cli
+```
+
+Run:
+```bash
+make install
+```
+
+## CI Dependencies
+
+The GitHub Actions CI workflow (`.github/workflows/ci.yml`) installs all dependencies automatically:
+1. Node.js 24 via `setup-node` action
+2. PostgreSQL 17 and Redis 7 via Docker services
+3. MinIO server and client downloaded during workflow
+4. Playwright for browser automation testing
+5. All package dependencies via `yarn install --frozen-lockfile`

QUICKSTART.md

@@ -21,31 +21,50 @@ This guide walks you through running your own Happy instance.
                               └─────────┘
 ```
 
-## Step 1: Build and Launch Services
+## Step 1: Install Dependencies
+
+On a fresh checkout, you first need to install all dependencies:
 
 ```bash
-cd .devcontainer
-make build                # Build the container image (first time only)
+make install              # Install dependencies for all components
+```
 
-# In terminal 1 - start the server (port 3005):
-make server
+This installs dependencies for:
+- `happy-cli` - CLI tool and daemon
+- `happy-server` - Backend server
+- `happy` (webapp) - Web interface
 
-# In terminal 2 - start the webapp (port 8081):
-make web
+## Step 2: Build and Launch Services
+
+```bash
+make build                # Build TypeScript code (happy-cli and happy-server)
+
+# Start all services (server + webapp):
+./happy-launcher.sh start
+
+# OR start just the backend (if you only need the server):
+./happy-launcher.sh start-backend
 ```
 
-## Step 2: Create an Account
+The launcher automatically starts:
+- PostgreSQL (port 5432)
+- Redis (port 6379)
+- MinIO (ports 9000/9001)
+- happy-server (port 3005)
+- Webapp (port 8081, if using `start`)
+
+## Step 3: Create an Account
 
 1. Open http://localhost:8081 in your browser
 2. Click "Create Account"
 3. Optionally add a recognizable username in Account settings
 
-## Step 3: Get Your Secret Key
+## Step 4: Get Your Secret Key
 
 1. Go to Account settings in the webapp
 2. Find and copy your secret backup key (format: `XXXXX-XXXXX-...`)
 
-## Step 4: Install the CLI
+## Step 5: Install the CLI
 
 On each machine where you want to run Claude with Happy:
 
@@ -55,21 +74,21 @@ cd /usr/local/happy
 npm install && npm run build && npm install -g .
 ```
 
-## Step 5: Authenticate the CLI
+## Step 6: Authenticate the CLI
 
 ```bash
 happy auth login --backup-key <YOUR-SECRET-KEY>
 ```
 
-## Step 6: Start the Daemon
+## Step 7: Start the Daemon
 
 ```bash
 happy daemon start
 ```
 
 The daemon connects your machine to the Happy server, allowing remote control from the webapp.
 
-## Step 7: (Optional) Voice Assistant
+## Step 8: (Optional) Voice Assistant
 
 For ElevenLabs voice assistant integration:
 

happy-launcher.sh

@@ -100,6 +100,41 @@ check_env_vars() {
 # Run the check
 check_env_vars
 
+# =============================================================================
+# Dependency Check
+# =============================================================================
+
+check_dependencies() {
+    local missing_deps=false
+
+    # Check if node_modules exist in each submodule
+    if [ ! -d "$CLI_DIR/node_modules" ]; then
+        error "Dependencies not installed in happy-cli"
+        missing_deps=true
+    fi
+
+    if [ ! -d "$SERVER_DIR/node_modules" ]; then
+        error "Dependencies not installed in happy-server"
+        missing_deps=true
+    fi
+
+    if [ ! -d "$WEBAPP_DIR/node_modules" ]; then
+        error "Dependencies not installed in happy webapp"
+        missing_deps=true
+    fi
+
+    if $missing_deps; then
+        echo ""
+        error "Dependencies are not installed. Please run:"
+        echo ""
+        echo "    make install"
+        echo ""
+        echo "This will install all required dependencies for happy-cli, happy-server, and happy webapp."
+        echo ""
+        exit 1
+    fi
+}
+
 # =============================================================================
 # Port Configuration with Slot Support
 # =============================================================================
@@ -907,6 +942,7 @@ test_connection() {
 
 case "${1:-}" in
     start)
+        check_dependencies
         info "Starting all services..."
         start_postgres
         start_redis
@@ -922,6 +958,7 @@ case "${1:-}" in
         ;;
 
     start-backend)
+        check_dependencies
         info "Starting backend services..."
         start_postgres
         start_redis
@@ -936,6 +973,7 @@ case "${1:-}" in
         ;;
 
     start-webapp)
+        check_dependencies
         start_webapp
         ;;