platform/SETUP_GUIDE.md

# Officer Setup Guide

## Overview

Officer is a self-hosted AI intranet for teams. This guide covers fresh installation on Ubuntu/Debian servers.

## Architecture

Officer uses **system-wide Node.js** to ensure all users have consistent access to tools:

```
System Node.js (v22, system-wide)
    ↓
npm global packages → /usr/local/lib/node_modules/
    ├── pi (coding agent)
    ├── claude (Claude Code)
    └── (available to all users)
    
Systemd Services
    ├── officer-pty-sidecar (terminal backend)
    └── (other services)
```

This is **not** an nvm-based setup. Each user doesn't install their own Node version. Instead:
- One system Node.js for everyone
- All npm packages installed system-wide
- Simple, predictable, production-friendly

---

## Installation Steps

### 1. Install Node.js 22 (System-Wide)

**On fresh Ubuntu/Debian:**

```bash
# Add NodeSource repository for Node 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js and npm
sudo apt-get install -y nodejs

# Verify for all users
node --version
npm --version

# Both should work regardless of which user runs it
```

**Already have an older Node version?**

```bash
# upgrade it
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# verify
node --version  # Should be v22.x.x
```

**Coming from nvm?**

```bash
# If you installed via nvm before, remove it
# Then install system Node as above
# nvm is NOT needed for Officer production setup
```

### 2. Run Setup Script

```bash
cd /path/to/officer/monorepo
bash scripts/setup.sh
```

This will:
- Install all system dependencies (git, build tools, ffmpeg, etc.)
- Install Bun, Go, Rust
- Install npm global packages (pi, claude-code, etc.)
- Setup PulseAudio for audio
- Setup remote desktop (XFCE + VNC)
- Configure PTY sidecar systemd service
- Verify everything works

**Note:** Setup script uses `sudo` for system-level installations. You'll be prompted for your password.

### 3. Verify Installation

```bash
# Everyone can use these (all users)
which node       # /usr/bin/node
which pi         # /usr/bin/pi
which claude     # /usr/bin/claude
which bun        # /home/user/.bun/bin/bun (or /usr/local/bin/bun)

# Test that pi works
pi --version
pi --list-models

# Test that Officer can start
bun dev

# In another terminal
curl http://localhost:5000/api/pi/models
```

### 4. Start Officer

**Development:**
```bash
bun dev
```

**Production (with PM2):**
```bash
pm2 start ecosystem.config.cjs
pm2 logs officer
```

**Production (with systemd):**
```bash
sudo systemctl start officer
sudo systemctl status officer
```

---

## Multi-User Scenarios

### Scenario A: Server with Multiple Users

All users automatically get access to:
- `node` command (system-wide)
- `pi`, `claude` (system-wide npm packages)
- Officer web UI (via port/proxy)

**No setup needed per user.** Just install globally once as shown above.

```bash
# User 1
$ which node
/usr/bin/node

# User 2 (different terminal/server)
$ which node
/usr/bin/node

# Both work!
```

### Scenario B: Development User Wants nvm

**Important:** For production, DON'T do this. But for dev, you can:

```bash
# As a user (not system-wide)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22

# Now you can use nvm locally, but make sure system Node is also installed for services
which node  # /home/user/.nvm/versions/node/v22.x.x/bin/node (your local override)
```

The `officer-pty-sidecar` systemd service will still use `/usr/bin/node` (system-wide).

---

## Troubleshooting

### "node: command not found"

**For a single user:**
```bash
# User's shell doesn't have node in PATH
# Make sure system Node is installed:
sudo apt-get install -y nodejs
node --version
```

**For systemd service:**
```bash
# Service can't find node
sudo systemctl status officer-pty-sidecar
journalctl -u officer-pty-sidecar

# Fix: Install system Node
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Restart service
sudo systemctl restart officer-pty-sidecar
```

### "pi: command not found"

```bash
# Pi not installed
sudo npm install -g @mariozechner/pi-coding-agent

# Or use setup script
bash scripts/setup.sh
```

### "Pi process exited with code 1" in chat

This usually means **snap node was used**. Don't use snap node for Officer.

```bash
# Check if snap node is installed
which node
# If output contains "/snap/bin/node", remove it:

sudo snap remove node

# Then install system Node
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
which node  # /usr/bin/node (NOT /snap/bin/node)
```

### PTY Sidecar service won't start

```bash
# Check status
sudo systemctl status officer-pty-sidecar

# Check logs
journalctl -u officer-pty-sidecar -n 20

# Verify Node is installed
/usr/bin/node --version

# Restart
sudo systemctl restart officer-pty-sidecar
```

---

## Files Changed/Created

- `scripts/setup.sh` — Main installation script (updated to use system Node)
- `scripts/setup-pty-sidecar.sh` — PTY sidecar systemd service setup (updated)
- `ecosystem.config.cjs` — PM2 config (no changes, using systemd instead)
- `SETUP_GUIDE.md` — This file

---

## What NOT To Do

❌ **Don't use snap node**
- It has file descriptor issues with piped processes
- Use system Node via NodeSource instead

❌ **Don't mix Node versions per user**
- For production: one Node version for everyone (system-wide)
- For dev: sure, use nvm, but keep system Node installed too

❌ **Don't install npm packages locally for system services**
- Services need system-wide packages (`sudo npm install -g`)
- Or use absolute paths in service files

✅ **Do:**
- Use system Node 22 via NodeSource
- Install global packages once with `sudo npm install -g`
- Use systemd services for daemons
- Let all users share the same tools

---

## Next Steps

1. Install Node.js: `curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs`
2. Run setup: `bash scripts/setup.sh`
3. Start Officer: `bun dev` (or PM2/systemd in production)
4. Open browser: `http://localhost:5000` (or your configured port)

---

## Support

If you hit issues:
1. Check troubleshooting section above
2. Verify system Node is installed: `node --version`
3. Check service logs: `journalctl -u officer-pty-sidecar`
4. Re-run setup script: `bash scripts/setup.sh`