Initial commit — OpenClaw VM infrastructure
- ansible/: VM provisioning playbooks and roles - provision-vm.yml: create KVM VM from Ubuntu cloud image - install.yml: install OpenClaw on guest (upstream) - customize.yml: swappiness, virtiofs fstab, linger - roles/vm/: libvirt domain XML, cloud-init templates - inventory.yml + host_vars/zap.yml: zap instance config - backup-openclaw-vm.sh: daily rsync + MinIO upload - restore-openclaw-vm.sh: full redeploy from scratch - README.md: full operational documentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
William Valentin
238
ansible/UPGRADE_NOTES.md
Normal file
238
ansible/UPGRADE_NOTES.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# 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**:
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user