fix: refactor setup scripts for system-wide Node.js (no nvm)
BREAKING: Officer now uses system Node.js via NodeSource instead of nvm. Changes: - Removed nvm sourcing from setup.sh - Updated Node installation to use NodeSource repository - All npm global packages installed system-wide with sudo - Updated PTY sidecar setup to use /usr/bin/node (system node) - Added Pi validation (test --list-models) - System packages now available to all users automatically Benefits: - Multi-user friendly: all users get same Node version - No per-user environment setup needed - Simpler troubleshooting (one node version) - Services use consistent node binary - Prevents snap node incompatibility issues Fixes: - 'node not found' for secondary users - systemd services finding correct node - Pi installation consistency across users New Files: - SETUP_GUIDE.md: Comprehensive installation guide - SETUP_ANALYSIS.md: Technical analysis of previous issues Migration: - Remove nvm if installed (optional) - Run: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - - Run: sudo apt-get install -y nodejs - Run: bash scripts/setup.sh
This commit is contained in:
+289
@@ -0,0 +1,289 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user