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 v22** to ensure all users have consistent access:

```
System Node.js v22 (/usr/bin/node)
    ↓
    All users automatically get:
    ├── node, npm, bun
    ├── pi, claude (coding agents)
    ├── go, rustc (compilers)
    └── All tools and services
    
Systemd Services (use system Node)
    ├── officer-pty-sidecar
    ├── officer (main server)
    └── (other services)
```

**Benefits:**
- One Node version for everyone (no conflicts)
- New users automatically get same setup
- Services use consistent environment
- Simple to maintain and troubleshoot
- Automatic installation (setup.sh handles it)

---

## Installation Steps

### Quick Start (One Command)

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

That's it! The script will:
- Install Node.js 22 automatically (if not found)
- Install all dependencies
- Setup all services
- Verify everything works

### What Happens Automatically

The setup script automatically:
1. Checks if Node 22 is installed
2. If not, sets up NodeSource repository and installs it
3. Installs all system packages, tools, and npm globals
4. Creates systemd services
5. Verifies everything works

**No manual Node installation needed!**

### Coming from nvm?

```bash
# If you previously installed via nvm, you can remove it
# (optional, won't interfere)
rm -rf ~/.nvm

# Or keep it for local dev, but system Node will take precedence for services
```

The system Node (installed by setup.sh) will be used by:
- All users
- All systemd services
- All npm global packages
- Officer server itself

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.

### Verify Installation

After setup.sh completes, verify as any user:

```bash
node --version       # v22.x.x
which pi             # /usr/bin/pi
which claude         # /usr/bin/claude
which bun            # /usr/local/bin/bun

# Test Pi works
pi --list-models

# Test Officer can start
bun dev

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

### 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"

This shouldn't happen if setup.sh ran successfully. But if it does:

```bash
# Run setup script again — it will install Node if missing
bash scripts/setup.sh

# Or manually install:
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
```

### "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

---

## Quick Start

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

Open browser: `http://localhost:5000` (or your configured port)

That's it! Everything is installed automatically.

---

## 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`