Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,14 @@
*.log
.ansible/
.vault_pass

# Secrets and credentials
*.env
.env*
secrets.yml
vault.yml
*.pem
*.key
id_rsa*
host_vars/
group_vars/
22 changes: 11 additions & 11 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Project Overview

Ansible playbook for automated, hardened Clawdbot installation on Debian/Ubuntu systems.
Ansible playbook for automated, hardened OpenClaw installation on Debian/Ubuntu systems.

## Key Principles

Expand All @@ -16,14 +16,14 @@ Ansible playbook for automated, hardened Clawdbot installation on Debian/Ubuntu
### Task Order
Docker must be installed **before** firewall configuration.

Task order in `roles/clawdbot/tasks/main.yml`:
Task order in `roles/openclaw/tasks/main.yml`:
```yaml
- tailscale.yml # VPN setup
- user.yml # Create system user
- docker.yml # Install Docker (creates /etc/docker)
- firewall.yml # Configure UFW + daemon.json (needs /etc/docker to exist)
- nodejs.yml # Node.js + pnpm
- clawdbot.yml # Container setup
- openclaw.yml # Container setup
```

Reason: `firewall.yml` writes `/etc/docker/daemon.json` and restarts Docker service.
Expand Down Expand Up @@ -110,16 +110,16 @@ Keep docs concise. No progress logs, no refactoring summaries.

### Host System
```
/opt/clawdbot/ # Installation files
/home/clawdbot/.clawdbot/ # Config and data
/etc/systemd/system/clawdbot.service
/opt/openclaw/ # Installation files
/home/openclaw/.openclaw/ # Config and data
/etc/systemd/system/openclaw.service
/etc/docker/daemon.json
/etc/ufw/after.rules
```

### Repository
```
roles/clawdbot/
roles/openclaw/
β”œβ”€β”€ tasks/ # Ansible tasks (order matters!)
β”œβ”€β”€ templates/ # Jinja2 configs
β”œβ”€β”€ defaults/ # Variables
Expand All @@ -141,7 +141,7 @@ SSH is exposed to the internet. Fail2ban automatically bans IPs after 5 failed a
Security patches should be applied promptly. Automatic security-only updates reduce vulnerability windows.

### Why Scoped Sudo?
The clawdbot user only needs to manage its own service and Tailscale. Full root access would be dangerous if the app is compromised.
The openclaw user only needs to manage its own service and Tailscale. Full root access would be dangerous if the app is compromised.

### Why Localhost Binding?
Defense in depth. If DOCKER-USER fails, localhost binding prevents external access.
Expand All @@ -160,7 +160,7 @@ Clean lifecycle, auto-start, logging integration.
## Making Changes

### Adding a New Task
1. Add to appropriate file in `roles/clawdbot/tasks/`
1. Add to appropriate file in `roles/openclaw/tasks/`
2. Update main.yml if new task file
3. Test with `--check` first
4. Verify idempotency (can run multiple times safely)
Expand All @@ -185,5 +185,5 @@ Clean lifecycle, auto-start, logging integration.

## Support Channels

- Clawdbot issues: https://github.com/clawdbot/clawdbot
- This installer: https://github.com/pasogott/clawdbot-ansible
- OpenClaw issues: https://github.com/openclaw/openclaw
- This installer: https://github.com/openclaw/openclaw-ansible
102 changes: 51 additions & 51 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@
- **Automatic OS detection** with proper fallback

#### Installation Modes
- **Release Mode** (default): Install via `pnpm install -g clawdbot@latest`
- **Release Mode** (default): Install via `pnpm install -g openclaw@latest`
- **Development Mode**: Clone repo, build from source, symlink binary
- Switch modes with `-e clawdbot_install_mode=development`
- Development aliases: `clawdbot-rebuild`, `clawdbot-dev`, `clawdbot-pull`
- 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 Clawdbot installation
- **pnpm package manager** used for OpenClaw installation

### πŸ› Bug Fixes

Expand All @@ -31,34 +31,34 @@
- **No more manual** `eval $(dbus-launch --sh-syntax)` needed!

2. **User Switching Command** βœ…
- Fixed: Changed from `sudo -i -u clawdbot` to `sudo su - clawdbot`
- Fixed: Changed from `sudo -i -u openclaw` to `sudo su - openclaw`
- Ensures proper login shell with .bashrc loading
- Alternative documented: `sudo -u clawdbot -i`
- Alternative documented: `sudo -u openclaw -i`

3. **Clawdbot Installation** βœ…
- Changed: `pnpm add -g` β†’ `pnpm install -g clawdbot@latest`
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 `clawdbot onboard --install-daemon` handle setup
- Let `openclaw onboard --install-daemon` handle setup
- Only create directory structure

### πŸ“¦ New Files Created

#### OS-Specific Task Files
```
roles/clawdbot/tasks/
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
β”œβ”€β”€ clawdbot-release.yml # Release mode installation
└── clawdbot-development.yml # Development mode installation
β”œβ”€β”€ openclaw-release.yml # Release mode installation
└── openclaw-development.yml # Development mode installation
```

#### Documentation
Expand All @@ -73,7 +73,7 @@ roles/clawdbot/tasks/
- Added OS detection (is_macos, is_debian, is_linux, is_redhat)
- Added apt update/upgrade at start
- Added Homebrew installation
- Enhanced welcome message with `clawdbot onboard --install-daemon`
- Enhanced welcome message with `openclaw onboard --install-daemon`
- Removed automatic config.yml creation

- **install.sh**
Expand All @@ -89,40 +89,40 @@ roles/clawdbot/tasks/
- **README.md**
- Updated for multi-OS support
- Added OS-specific requirements
- Updated quick-start with `clawdbot onboard --install-daemon`
- Updated quick-start with `openclaw onboard --install-daemon`
- Added Homebrew to feature list

#### Role Files
- **roles/clawdbot/defaults/main.yml**
- **roles/openclaw/defaults/main.yml**
- Added OS-specific variables (homebrew_prefix, package_manager)

- **roles/clawdbot/tasks/main.yml**
- **roles/openclaw/tasks/main.yml**
- No changes (orchestrator)

- **roles/clawdbot/tasks/system-tools.yml**
- **roles/openclaw/tasks/system-tools.yml**
- Refactored to delegate to OS-specific files
- Added fail-safe for unsupported OS

- **roles/clawdbot/tasks/docker.yml**
- **roles/openclaw/tasks/docker.yml**
- Refactored to delegate to OS-specific files

- **roles/clawdbot/tasks/firewall.yml**
- **roles/openclaw/tasks/firewall.yml**
- Refactored to delegate to OS-specific files

- **roles/clawdbot/tasks/user.yml**
- **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/clawdbot/tasks/clawdbot.yml**
- Changed to `pnpm install -g clawdbot@latest`
- **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/clawdbot/templates/clawdbot-host.service.j2**
- **roles/openclaw/templates/openclaw-host.service.j2**
- Added XDG_RUNTIME_DIR environment
- Added DBUS_SESSION_BUS_ADDRESS
- Added Homebrew to PATH
Expand All @@ -134,46 +134,46 @@ roles/clawdbot/tasks/
```bash
# Installation
curl -fsSL https://.../install.sh | bash
sudo -i -u clawdbot # ❌ Wrong command
nano ~/.clawdbot/config.yml # Manual config
clawdbot login # Manual setup
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)
```bash
# Installation
curl -fsSL https://.../install.sh | bash
sudo su - clawdbot # βœ… Correct command
clawdbot onboard --install-daemon # βœ… One command setup!
sudo su - openclaw # βœ… Correct command
openclaw onboard --install-daemon # βœ… One command setup!
# DBus auto-configured # βœ… Works
# Service auto-installed # βœ… Works
```

#### New Workflow - Development Mode
```bash
# Installation with development mode
git clone https://github.com/pasogott/clawdbot-ansible.git
cd clawdbot-ansible
./run-playbook.sh -e clawdbot_install_mode=development
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
./run-playbook.sh -e openclaw_install_mode=development

# Switch to clawdbot user
sudo su - clawdbot
# Switch to openclaw user
sudo su - openclaw

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

# Test immediately
clawdbot doctor # Uses new build
openclaw doctor # Uses new build
```

### 🎯 User Experience Improvements

#### Welcome Message
- Shows environment status (XDG_RUNTIME_DIR, DBUS, Homebrew, Clawdbot version)
- Recommends `clawdbot onboard --install-daemon` as primary command
- 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

Expand All @@ -186,12 +186,12 @@ clawdbot doctor # Uses new build
#### Directory Structure
Ansible creates only structure, no config files:
```
~/.clawdbot/
~/.openclaw/
β”œβ”€β”€ sessions/ # Created (empty)
β”œβ”€β”€ credentials/ # Created (secure: 0700)
β”œβ”€β”€ data/ # Created (empty)
└── logs/ # Created (empty)
# clawdbot.json # NOT created - user's clawdbot creates it
# openclaw.json # NOT created - user's openclaw creates it
# config.yml # NOT created - deprecated
```

Expand All @@ -200,11 +200,11 @@ Ansible creates only structure, no config files:
#### Systemd Service Hardening
- `ProtectSystem=strict` - System directories read-only
- `ProtectHome=read-only` - Limited home access
- `ReadWritePaths=~/.clawdbot` - Only config writable
- `ReadWritePaths=~/.openclaw` - Only config writable
- `NoNewPrivileges=true` - No privilege escalation

#### User Isolation
- Dedicated clawdbot system user
- Dedicated openclaw system user
- lingering enabled for systemd user services
- Proper DBus session isolation
- XDG_RUNTIME_DIR per-user
Expand All @@ -219,23 +219,23 @@ Ansible creates only structure, no config files:
| Firewall | UFW | Application FW | Working |
| systemd | βœ… | ❌ | Linux only |
| DBus Setup | βœ… | N/A | Linux only |
| pnpm + Clawdbot | βœ… | βœ… | Working |
| pnpm + OpenClaw | βœ… | βœ… | Working |

### ⚠️ Breaking Changes

1. **User Switch Command Changed**
- Old: `sudo -i -u clawdbot`
- New: `sudo su - clawdbot`
- 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 `clawdbot onboard`
- New: User runs `openclaw onboard`
- Impact: Users must run onboard command

3. **No Auto-Service Install**
- Old: systemd service auto-installed
- New: `clawdbot onboard --install-daemon`
- New: `openclaw onboard --install-daemon`
- Impact: Service not running after ansible

### πŸ”„ Migration Guide
Expand All @@ -249,16 +249,16 @@ Just run the new installer - everything works out of the box!
echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc

# 2. Enable lingering
sudo loginctl enable-linger clawdbot
sudo loginctl enable-linger openclaw

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

# 4. Reload
source ~/.bashrc

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

### πŸ“š Documentation Updates
Expand All @@ -285,7 +285,7 @@ pnpm install -g clawdbot@latest

### πŸ™ Credits

Based on user feedback and real-world usage patterns from the clawdbot community.
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!

Expand Down
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2025 Clawdbot Contributors
Copyright (c) 2025 OpenClaw Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
Loading