swarm-master/ansible/UPGRADE_NOTES.md

Upgrade Notes - Option A Implementation

✅ Completed Changes

1. Installation Modes (Release vs Development)

• File: roles/openclaw/defaults/main.yml
• Added openclaw_install_mode variable (release | development)
• Release mode: Install via pnpm install -g openclaw@latest (default)
• Development mode: Clone repo, build, symlink binary
• Development settings: repo URL, branch, code directory

Files Created:

• roles/openclaw/tasks/openclaw-release.yml - npm installation
• roles/openclaw/tasks/openclaw-development.yml - git clone + build
• docs/development-mode.md - comprehensive guide

Development Mode Features:

• Clones to ~/code/openclaw
• Runs pnpm install and pnpm build
• Symlinks bin/openclaw.js to ~/.local/bin/openclaw
• Adds aliases: openclaw-rebuild, openclaw-dev, openclaw-pull
• Sets OPENCLAW_DEV_DIR environment variable

Usage:

# Release mode (default)
./run-playbook.sh

# Development mode
./run-playbook.sh -e openclaw_install_mode=development

# With custom repo
ansible-playbook playbook.yml --ask-become-pass \
  -e openclaw_install_mode=development \
  -e openclaw_repo_url=https://github.com/YOUR_USERNAME/openclaw.git \
  -e openclaw_repo_branch=feature-branch

2. OS Detection & apt update/upgrade

• File: playbook.yml
• Added OS detection in pre_tasks (macOS, Debian/Ubuntu, RedHat)
• Added apt update && apt upgrade at the beginning (Debian/Ubuntu only)
• Detection variables: is_macos, is_linux, is_debian, is_redhat

2. Homebrew Installation

• File: playbook.yml
• Homebrew is now installed for both Linux and macOS
• Linux: /home/linuxbrew/.linuxbrew/bin/brew
• macOS: /opt/homebrew/bin/brew
• Automatically added to PATH

3. OS-Specific System Tools

• Files:
  • roles/openclaw/tasks/system-tools.yml (orchestrator)
  • roles/openclaw/tasks/system-tools-linux.yml (apt-based)
  • roles/openclaw/tasks/system-tools-macos.yml (brew-based)
• Tools installed via appropriate package manager per OS
• Homebrew shellenv integrated into .zshrc

4. OS-Specific Docker Installation

• Files:
  • roles/openclaw/tasks/docker.yml (orchestrator)
  • roles/openclaw/tasks/docker-linux.yml (Docker CE)
  • roles/openclaw/tasks/docker-macos.yml (Docker Desktop)
• Linux: Docker CE via apt
• macOS: Docker Desktop via Homebrew Cask

5. OS-Specific Firewall Configuration

• Files:
  • roles/openclaw/tasks/firewall.yml (orchestrator)
  • roles/openclaw/tasks/firewall-linux.yml (UFW)
  • roles/openclaw/tasks/firewall-macos.yml (Application Firewall)
• Linux: UFW with Docker isolation
• macOS: Application Firewall configuration

6. DBus & systemd User Service Fixes

• File: roles/openclaw/tasks/user.yml
• Fixed: loginctl enable-linger for openclaw user
• Fixed: XDG_RUNTIME_DIR set to /run/user/$(id -u)
• Fixed: DBUS_SESSION_BUS_ADDRESS configuration in .bashrc
• No more manual eval $(dbus-launch --sh-syntax) needed!

7. Systemd Service Template Enhancement

• File: roles/openclaw/templates/openclaw-host.service.j2
• Added XDG_RUNTIME_DIR environment variable
• Added DBUS_SESSION_BUS_ADDRESS
• Added Homebrew to PATH
• Enhanced security with ProtectSystem and ProtectHome

8. OpenClaw Installation via pnpm

• File: roles/openclaw/tasks/openclaw.yml
• Changed from pnpm add -g to pnpm install -g openclaw@latest
• Added verification step
• Added version display

9. Correct User Switching Command

• File: run-playbook.sh
• Changed from sudo -i -u openclaw to sudo su - openclaw
• Alternative: sudo -u openclaw -i
• Ensures proper login shell with .bashrc loaded

10. Enhanced Welcome Message

• File: playbook.yml (post_tasks)
• Recommends: openclaw onboard --install-daemon as first command
• Shows environment status (XDG_RUNTIME_DIR, DBUS, Homebrew)
• Provides both quick-start and manual setup paths
• More helpful command examples

11. Multi-OS Install Script

• File: install.sh
• Removed Debian/Ubuntu-only check
• Added OS detection for macOS and Linux
• Proper messaging for detected OS

12. Updated Documentation

• File: README.md
• Multi-OS badge (Debian | Ubuntu | macOS)
• Updated features list
• Added OS-specific requirements
• Added post-install instructions with openclaw onboard --install-daemon

🎯 Key Improvements

Fixed Issues from User History

1. ✅ DBus errors: Automatically configured, no manual setup needed
2. ✅ User switching: Correct command (sudo su - openclaw)
3. ✅ Environment: XDG_RUNTIME_DIR and DBUS properly set
4. ✅ Homebrew: Integrated and in PATH
5. ✅ pnpm: Uses pnpm install -g openclaw@latest

OS Detection Framework

• Clean separation between Linux and macOS tasks
• Easy to extend for other distros
• Fails gracefully with clear error messages

Better User Experience

• Clear next steps after installation
• Recommends openclaw onboard --install-daemon
• Helpful welcome message with environment status
• Proper shell initialization

🔄 Migration Path

For Existing Installations

If you have an existing installation, you may need to:

# 1. Update environment variables
echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc

# 2. Enable lingering
sudo loginctl enable-linger openclaw

# 3. Add Homebrew to PATH (if using Linux)
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc

# 4. Reload shell
source ~/.bashrc

# 5. Reinstall openclaw
pnpm install -g openclaw@latest

📝 TODO - Future macOS Enhancements

Items NOT Yet Implemented (for future)

• macOS-specific user creation (different from Linux)
• launchd service instead of systemd (macOS)
• Full pf firewall configuration (macOS)
• macOS-specific Tailscale configuration
• Testing on actual macOS hardware

Current macOS Status

• ✅ Basic framework in place
• ✅ Homebrew installation works
• ✅ Docker Desktop installation configured
• ⚠️ Some tasks may need macOS testing/refinement

🧪 Testing Recommendations

Linux (Debian/Ubuntu)

# Test OS detection
ansible-playbook playbook.yml --ask-become-pass --tags=never -vv

# Test full installation
./run-playbook.sh

# Verify openclaw
sudo su - openclaw
openclaw --version
openclaw onboard --install-daemon

macOS (Future)

# Similar process, but may need refinements
# Recommend thorough testing before production use

🔒 Security Notes

Enhanced systemd Security

• ProtectSystem=strict: Read-only system directories
• ProtectHome=read-only: Limited home access
• ReadWritePaths: Only ~/.openclaw writable
• NoNewPrivileges: Prevents privilege escalation

DBus Session Security

• User-specific DBus session
• Proper XDG_RUNTIME_DIR isolation
• No root access required for daemon

📚 Related Files

Modified Files

• playbook.yml - Main orchestration with OS detection
• install.sh - Multi-OS detection
• run-playbook.sh - Correct user switch command
• README.md - Multi-OS documentation
• roles/openclaw/defaults/main.yml - OS-specific variables
• roles/openclaw/tasks/*.yml - OS-aware task orchestration
• roles/openclaw/templates/openclaw-host.service.j2 - Enhanced service

New Files Created

• roles/openclaw/tasks/system-tools-linux.yml
• roles/openclaw/tasks/system-tools-macos.yml
• roles/openclaw/tasks/docker-linux.yml
• roles/openclaw/tasks/docker-macos.yml
• roles/openclaw/tasks/firewall-linux.yml
• roles/openclaw/tasks/firewall-macos.yml
• UPGRADE_NOTES.md (this file)

---

Implementation Date: January 2025 Implementation: Option A (Incremental multi-OS support) Status: ✅ Complete and ready for testing