How to Deploy & Use slopus/happy

# Happy Coder Deployment & Usage Guide

## Prerequisites

- **Node.js** 18.x LTS or higher
- **Yarn** 1.22.x or 3.x+ (Berry)
- **Git** 2.30+
- **Expo CLI** (for mobile development): `npm install -g expo-cli`
- **iOS Development**: macOS with Xcode 14+ (for iOS builds)
- **Android Development**: Android Studio with SDK 33+
- **Optional**: EAS CLI for mobile builds (`npm install -g eas-cli`)

## Installation

### Clone the Repository

```bash
git clone https://github.com/slopus/happy.git
cd happy

Install Dependencies

Install all workspace dependencies from the monorepo root:

yarn install

Install CLI Globally (Optional)

For using happy command system-wide without building:

npm install -g happy-coder

Configuration

Server Environment Variables

Create .env in packages/happy-server/:

# Server
PORT=3000
NODE_ENV=production

# Encryption
ENCRYPTION_KEY=your-32-character-secret-key-here

# Database (if using persistent storage)
DATABASE_URL=postgresql://user:pass@localhost:5432/happy

# Redis (for real-time sync)
REDIS_URL=redis://localhost:6379

CLI Configuration

On first run, the CLI creates a config file at ~/.happy/config.json:

{
  "serverUrl": "https://your-server-domain.com",
  "userId": "your-user-uuid",
  "encryptionKey": "auto-generated-key"
}

Or configure via environment variables:

export HAPPY_SERVER_URL=https://your-server-domain.com
export HAPPY_API_KEY=your-api-key

Mobile App Configuration

Create packages/happy-app/.env.local:

API_URL=https://your-server-domain.com
WS_URL=wss://your-server-domain.com
ENABLE_ENCRYPTION=true

Build & Run

Development Mode

Run CLI from source:

# From repository root
yarn cli --help
yarn cli codex

Start the server:

cd packages/happy-server
yarn dev

Start mobile app:

cd packages/happy-app
yarn start
# Press 'i' for iOS simulator, 'a' for Android emulator

Production Build

Build all packages:

yarn release

Build specific packages:

# Server
cd packages/happy-server
yarn build
yarn start

# CLI
cd packages/happy-cli
yarn build
npm link  # Makes 'happy' command available globally

# Mobile (via Expo)
cd packages/happy-app
eas build --platform ios
eas build --platform android
eas build --platform web

Deployment

Deploying the Server

Option 1: Railway/Render (Recommended)

1. Connect GitHub repo to Railway or Render
2. Set root directory to packages/happy-server
3. Add environment variables from Configuration section
4. Deploy (auto-detects Node.js)

Option 2: Docker

# Dockerfile in packages/happy-server
FROM node:18-alpine
WORKDIR /app
COPY package.json yarn.lock ./
COPY packages/happy-server ./packages/happy-server
RUN yarn install --frozen-lockfile
WORKDIR /app/packages/happy-server
EXPOSE 3000
CMD ["yarn", "start"]

Option 3: VPS (Ubuntu)

# Build locally
yarn release

# Copy dist to server
scp -r packages/happy-server/dist user@server:/var/www/happy-server

# On server
cd /var/www/happy-server
npm install --production
pm2 start index.js --name happy-server

Deploying the Web App

Vercel:

1. Import project, set framework preset to "Other"
2. Build command: cd packages/happy-app && expo build:web
3. Output directory: packages/happy-app/web-build

Netlify: Connect repo with build settings:

• Build command: yarn workspace happy-app build:web
• Publish directory: packages/happy-app/dist

Mobile App Store Deployment

cd packages/happy-app

# iOS
eas build --platform ios --auto-submit

# Android
eas build --platform android --auto-submit

Configure app.json with your bundle identifiers and API keys before building.

Troubleshooting

CLI Connection Issues

Problem: happy command not found after global install Solution:

npm config get prefix  # Check global bin path
export PATH="$PATH:$(npm config get prefix)/bin"

Problem: "Cannot connect to agent" error Solution: Ensure the server is running and HAPPY_SERVER_URL points to the correct address. Check firewall rules on port 3000 (or your configured port).

Build Errors

Problem: Cannot find module '@agentclientprotocol/sdk' Solution:

yarn install
# If persists:
yarn workspace happy-cli add @agentclientprotocol/sdk

Problem: Monorepo workspace linking errors Solution:

yarn install --check-files
yarn workspaces foreach run build

Mobile Development

Problem: Metro bundler crashes with "ENOSPC" Solution: Increase file watchers limit:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Problem: iOS build fails with signing errors Solution:

1. Open packages/happy-app/ios in Xcode
2. Select team in Signing & Capabilities
3. Run: yarn ios from package directory

Server Deployment

Problem: WebSocket connections fail behind nginx Solution: Update nginx config:

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Problem: Encryption key errors Solution: Ensure ENCRYPTION_KEY is exactly 32 characters for AES-256-GCM. Generate with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"