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:

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

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

# 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

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

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

bun dev

Production (with PM2):

pm2 start ecosystem.config.cjs
pm2 logs officer

Production (with systemd):

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.

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

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

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

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

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

# 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

# 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