swarm-master/ansible/CHANGELOG.md

Changelog - Multi-OS Support & Bug Fixes

[2.0.0] - 2025-01-09

🎉 Major Changes

Multi-OS Support

• Added macOS support alongside Debian/Ubuntu
• Homebrew installation for both Linux and macOS
• OS-specific task files for clean separation
• Automatic OS detection with proper fallback

Installation Modes

• Release Mode (default): Install via pnpm install -g openclaw@latest
• Development Mode: Clone repo, build from source, symlink binary
• Switch modes with -e openclaw_install_mode=development
• Development aliases: openclaw-rebuild, openclaw-dev, openclaw-pull

System Improvements

• apt update & upgrade runs automatically at start (Debian/Ubuntu)
• Homebrew integrated in PATH for all users
• pnpm package manager used for OpenClaw installation

🐛 Bug Fixes

Critical Fixes from User Feedback

1. DBus Session Bus Issues ✅

   • Fixed: loginctl enable-linger now configured automatically
   • Fixed: XDG_RUNTIME_DIR set in .bashrc
   • Fixed: DBUS_SESSION_BUS_ADDRESS configured properly
   • No more manual eval $(dbus-launch --sh-syntax) needed!

2. User Switching Command ✅

   • Fixed: Changed from sudo -i -u openclaw to sudo su - openclaw
   • Ensures proper login shell with .bashrc loading
   • Alternative documented: sudo -u openclaw -i

3. OpenClaw Installation ✅

   • Changed: pnpm add -g → pnpm install -g openclaw@latest
   • Added installation verification
   • Added version display

4. Configuration Management ✅

   • Removed automatic config.yml creation
   • Removed automatic systemd service installation
   • Let openclaw onboard --install-daemon handle setup
   • Only create directory structure

📦 New Files Created

OS-Specific Task Files

roles/openclaw/tasks/
├── system-tools-linux.yml      # apt-based tool installation
├── system-tools-macos.yml      # brew-based tool installation
├── docker-linux.yml            # Docker CE installation
├── docker-macos.yml            # Docker Desktop installation
├── firewall-linux.yml          # UFW configuration
├── firewall-macos.yml          # Application Firewall config
├── openclaw-release.yml        # Release mode installation
└── openclaw-development.yml    # Development mode installation

Documentation

• UPGRADE_NOTES.md - Detailed upgrade information
• CHANGELOG.md - This file
• docs/development-mode.md - Development mode guide

🔧 Modified Files

Core Playbook & Scripts

• playbook.yml

  • Added OS detection (is_macos, is_debian, is_linux, is_redhat)
  • Added apt update/upgrade at start
  • Added Homebrew installation
  • Enhanced welcome message with openclaw onboard --install-daemon
  • Removed automatic config.yml creation

• install.sh

  • Added macOS detection
  • Removed Debian-only restriction
  • Better error messages for unsupported OS

• run-playbook.sh

  • Fixed user switch command documentation
  • Added alternative command options
  • Enhanced post-install instructions

• README.md

  • Updated for multi-OS support
  • Added OS-specific requirements
  • Updated quick-start with openclaw onboard --install-daemon
  • Added Homebrew to feature list

Role Files

• roles/openclaw/defaults/main.yml

  • Added OS-specific variables (homebrew_prefix, package_manager)

• roles/openclaw/tasks/main.yml

  • No changes (orchestrator)

• roles/openclaw/tasks/system-tools.yml

  • Refactored to delegate to OS-specific files
  • Added fail-safe for unsupported OS

• roles/openclaw/tasks/docker.yml

  • Refactored to delegate to OS-specific files

• roles/openclaw/tasks/firewall.yml

  • Refactored to delegate to OS-specific files

• roles/openclaw/tasks/user.yml

  • Added loginctl enable-linger
  • Added XDG_RUNTIME_DIR configuration
  • Added DBUS_SESSION_BUS_ADDRESS setup
  • Fixed systemd user service support

• roles/openclaw/tasks/openclaw.yml

  • Changed to pnpm install -g openclaw@latest
  • Added installation verification
  • Removed config.yml template generation
  • Removed systemd service installation
  • Only creates directory structure

• roles/openclaw/templates/openclaw-host.service.j2

  • Added XDG_RUNTIME_DIR environment
  • Added DBUS_SESSION_BUS_ADDRESS
  • Added Homebrew to PATH
  • Enhanced security settings (ProtectSystem, ProtectHome)

🚀 Workflow Changes

Old Workflow

# Installation
curl -fsSL https://.../install.sh | bash
sudo -i -u openclaw              # ❌ Wrong command
nano ~/.openclaw/config.yml      # Manual config
openclaw login                   # Manual setup
# Missing DBus setup              # ❌ Errors

New Workflow - Release Mode (Default)

# Installation
curl -fsSL https://.../install.sh | bash
sudo su - openclaw               # ✅ Correct command
openclaw onboard --install-daemon # ✅ One command setup!
# DBus auto-configured             # ✅ Works
# Service auto-installed           # ✅ Works

New Workflow - Development Mode

# Installation with development mode
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
./run-playbook.sh -e openclaw_install_mode=development

# Switch to openclaw user
sudo su - openclaw

# Make changes
openclaw-dev              # cd ~/code/openclaw
vim src/some-file.ts      # Edit code
openclaw-rebuild          # pnpm build

# Test immediately
openclaw doctor           # Uses new build

🎯 User Experience Improvements

Welcome Message

• Shows environment status (XDG_RUNTIME_DIR, DBUS, Homebrew, OpenClaw version)
• Recommends openclaw onboard --install-daemon as primary command
• Provides manual setup steps as alternative
• Lists useful commands for troubleshooting

Environment Configuration

• Homebrew automatically added to PATH
• pnpm global bin directory configured
• DBus session bus properly initialized
• XDG_RUNTIME_DIR set for systemd user services

Directory Structure

Ansible creates only structure, no config files:

~/.openclaw/
├── sessions/       # Created (empty)
├── credentials/    # Created (secure: 0700)
├── data/          # Created (empty)
└── logs/          # Created (empty)
# openclaw.json    # NOT created - user's openclaw creates it
# config.yml       # NOT created - deprecated

🔒 Security Enhancements

Systemd Service Hardening

• ProtectSystem=strict - System directories read-only
• ProtectHome=read-only - Limited home access
• ReadWritePaths=~/.openclaw - Only config writable
• NoNewPrivileges=true - No privilege escalation

User Isolation

• Dedicated openclaw system user
• lingering enabled for systemd user services
• Proper DBus session isolation
• XDG_RUNTIME_DIR per-user

📊 Platform Support Matrix

Feature	Debian/Ubuntu	macOS	Status
Base Installation	✅	✅	Tested
Homebrew	✅	✅	Working
Docker	Docker CE	Docker Desktop	Working
Firewall	UFW	Application FW	Working
systemd	✅	❌	Linux only
DBus Setup	✅	N/A	Linux only
pnpm + OpenClaw	✅	✅	Working

⚠️ Breaking Changes

1. User Switch Command Changed

   • Old: sudo -i -u openclaw
   • New: sudo su - openclaw
   • Impact: Update documentation, scripts

2. No Auto-Configuration

   • Old: config.yml auto-created
   • New: User runs openclaw onboard
   • Impact: Users must run onboard command

3. No Auto-Service Install

   • Old: systemd service auto-installed
   • New: openclaw onboard --install-daemon
   • Impact: Service not running after ansible

🔄 Migration Guide

For Fresh Installations

Just run the new installer - everything works out of the box!

For Existing Installations

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

# 2. Enable lingering
sudo loginctl enable-linger openclaw

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

# 4. Reload
source ~/.bashrc

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

📚 Documentation Updates

• README.md: Multi-OS support documented
• UPGRADE_NOTES.md: Detailed technical changes
• CHANGES.md: User-facing changelog (this file)
• install.sh: Updated help text
• run-playbook.sh: Better instructions

🐛 Known Issues

macOS Limitations

• systemd not available (Linux feature)
• Some Linux-specific tools not installed
• Firewall configuration limited
• Recommendation: Use for development, not production

Future Enhancements

• launchd support for macOS service management
• Full pf firewall configuration for macOS
• macOS-specific user management
• Cross-platform testing suite

🙏 Credits

Based on user feedback and real-world usage patterns from the openclaw community.

Special thanks to early testers who identified the DBus and user switching issues!

---

For detailed technical information, see UPGRADE_NOTES.md

For installation instructions, see README.md