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
408
ansible/docs/configuration.md
Normal file
408
ansible/docs/configuration.md
Normal file
@@ -0,0 +1,408 @@
|
||||
# Configuration Guide
|
||||
|
||||
This guide explains all available configuration options for the OpenClaw Ansible installer.
|
||||
|
||||
## Configuration File
|
||||
|
||||
All default variables are defined in:
|
||||
**[`roles/openclaw/defaults/main.yml`](../roles/openclaw/defaults/main.yml)**
|
||||
|
||||
## How to Configure
|
||||
|
||||
### Method 1: Command Line Variables
|
||||
|
||||
Pass variables directly via `-e` flag:
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass \
|
||||
-e openclaw_install_mode=development \
|
||||
-e "openclaw_ssh_keys=['ssh-ed25519 AAAAC3... user@host']"
|
||||
```
|
||||
|
||||
### Method 2: Variables File
|
||||
|
||||
Create a `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
# vars.yml
|
||||
openclaw_install_mode: development
|
||||
openclaw_ssh_keys:
|
||||
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx user@host"
|
||||
- "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... admin@laptop"
|
||||
openclaw_repo_url: "https://github.com/YOUR_USERNAME/openclaw.git"
|
||||
openclaw_repo_branch: "main"
|
||||
tailscale_authkey: "tskey-auth-xxxxxxxxxxxxx"
|
||||
nodejs_version: "22.x"
|
||||
```
|
||||
|
||||
Then use it:
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass -e @vars.yml
|
||||
```
|
||||
|
||||
### Method 3: Edit Defaults
|
||||
|
||||
Directly edit `roles/openclaw/defaults/main.yml` before running the playbook.
|
||||
|
||||
**Note**: This is not recommended for version control, use variables files instead.
|
||||
|
||||
## Available Variables
|
||||
|
||||
### User Configuration
|
||||
|
||||
#### `openclaw_user`
|
||||
- **Type**: String
|
||||
- **Default**: `openclaw`
|
||||
- **Description**: System user name for running OpenClaw
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_user=myuser
|
||||
```
|
||||
|
||||
#### `openclaw_home`
|
||||
- **Type**: String
|
||||
- **Default**: `/home/openclaw`
|
||||
- **Description**: Home directory for the openclaw user
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_home=/home/myuser
|
||||
```
|
||||
|
||||
#### `openclaw_ssh_keys`
|
||||
- **Type**: List of strings
|
||||
- **Default**: `[]` (empty)
|
||||
- **Description**: SSH public keys for accessing the openclaw user account
|
||||
- **Example**:
|
||||
```yaml
|
||||
openclaw_ssh_keys:
|
||||
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx user@host"
|
||||
- "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... admin@laptop"
|
||||
```
|
||||
```bash
|
||||
-e "openclaw_ssh_keys=['ssh-ed25519 AAAAC3... user@host']"
|
||||
```
|
||||
|
||||
### Installation Mode
|
||||
|
||||
#### `openclaw_install_mode`
|
||||
- **Type**: String (`release` or `development`)
|
||||
- **Default**: `release`
|
||||
- **Description**: Installation mode
|
||||
- `release`: Install via npm (`pnpm install -g openclaw@latest`)
|
||||
- `development`: Clone repo, build from source, symlink binary
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_install_mode=development
|
||||
```
|
||||
|
||||
### Development Mode Settings
|
||||
|
||||
These variables only apply when `openclaw_install_mode: development`
|
||||
|
||||
#### `openclaw_repo_url`
|
||||
- **Type**: String (Git URL)
|
||||
- **Default**: `https://github.com/openclaw/openclaw.git`
|
||||
- **Description**: Git repository URL to clone
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_repo_url=https://github.com/YOUR_USERNAME/openclaw.git
|
||||
```
|
||||
|
||||
#### `openclaw_repo_branch`
|
||||
- **Type**: String
|
||||
- **Default**: `main`
|
||||
- **Description**: Git branch to checkout
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_repo_branch=feature-branch
|
||||
```
|
||||
|
||||
#### `openclaw_code_dir`
|
||||
- **Type**: String (Path)
|
||||
- **Default**: `{{ openclaw_home }}/code`
|
||||
- **Description**: Directory where code repositories are stored
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_code_dir=/home/openclaw/projects
|
||||
```
|
||||
|
||||
#### `openclaw_repo_dir`
|
||||
- **Type**: String (Path)
|
||||
- **Default**: `{{ openclaw_code_dir }}/openclaw`
|
||||
- **Description**: Full path to openclaw repository
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_repo_dir=/home/openclaw/projects/openclaw
|
||||
```
|
||||
|
||||
### OpenClaw Settings
|
||||
|
||||
#### `openclaw_port`
|
||||
- **Type**: Integer
|
||||
- **Default**: `3000`
|
||||
- **Description**: Port for OpenClaw gateway (currently informational)
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_port=8080
|
||||
```
|
||||
|
||||
#### `openclaw_config_dir`
|
||||
- **Type**: String (Path)
|
||||
- **Default**: `{{ openclaw_home }}/.openclaw`
|
||||
- **Description**: OpenClaw configuration directory
|
||||
- **Example**:
|
||||
```bash
|
||||
-e openclaw_config_dir=/etc/openclaw
|
||||
```
|
||||
|
||||
### Node.js Configuration
|
||||
|
||||
#### `nodejs_version`
|
||||
- **Type**: String
|
||||
- **Default**: `22.x`
|
||||
- **Description**: Node.js major version to install
|
||||
- **Example**:
|
||||
```bash
|
||||
-e nodejs_version=20.x
|
||||
```
|
||||
|
||||
### Tailscale Configuration
|
||||
|
||||
#### `tailscale_authkey`
|
||||
- **Type**: String
|
||||
- **Default**: `""` (empty - manual setup required)
|
||||
- **Description**: Tailscale authentication key for automatic connection
|
||||
- **Example**:
|
||||
```bash
|
||||
-e tailscale_authkey=tskey-auth-k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6
|
||||
```
|
||||
- **Get Key**: https://login.tailscale.com/admin/settings/keys
|
||||
|
||||
### OS-Specific Settings
|
||||
|
||||
These are automatically set based on the detected OS:
|
||||
|
||||
#### `homebrew_prefix`
|
||||
- **Type**: String (Path)
|
||||
- **Default**: `/opt/homebrew` (macOS) or `/home/linuxbrew/.linuxbrew` (Linux)
|
||||
- **Description**: Homebrew installation prefix
|
||||
- **Read-only**: Set automatically based on OS
|
||||
|
||||
#### `package_manager`
|
||||
- **Type**: String
|
||||
- **Default**: `brew` (macOS) or `apt` (Linux)
|
||||
- **Description**: System package manager
|
||||
- **Read-only**: Set automatically based on OS
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Basic Setup with SSH Keys
|
||||
|
||||
```yaml
|
||||
# vars.yml
|
||||
openclaw_ssh_keys:
|
||||
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx user@desktop"
|
||||
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHyyyyyyyy user@laptop"
|
||||
```
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass -e @vars.yml
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
```yaml
|
||||
# vars-dev.yml
|
||||
openclaw_install_mode: development
|
||||
openclaw_repo_url: "https://github.com/myorg/openclaw.git"
|
||||
openclaw_repo_branch: "develop"
|
||||
openclaw_ssh_keys:
|
||||
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx dev@workstation"
|
||||
```
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass -e @vars-dev.yml
|
||||
```
|
||||
|
||||
### Production Setup with Tailscale
|
||||
|
||||
```yaml
|
||||
# vars-prod.yml
|
||||
openclaw_install_mode: release
|
||||
tailscale_authkey: "tskey-auth-k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"
|
||||
openclaw_ssh_keys:
|
||||
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx admin@mgmt-server"
|
||||
nodejs_version: "22.x"
|
||||
```
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass -e @vars-prod.yml
|
||||
```
|
||||
|
||||
### Custom User and Directories
|
||||
|
||||
```yaml
|
||||
# vars-custom.yml
|
||||
openclaw_user: mybot
|
||||
openclaw_home: /opt/mybot
|
||||
openclaw_config_dir: /etc/mybot
|
||||
openclaw_code_dir: /opt/mybot/repositories
|
||||
```
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass -e @vars-custom.yml
|
||||
```
|
||||
|
||||
### Testing Different Branches
|
||||
|
||||
```yaml
|
||||
# vars-testing.yml
|
||||
openclaw_install_mode: development
|
||||
openclaw_repo_branch: "experimental-feature"
|
||||
openclaw_ssh_keys:
|
||||
- "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx tester@qa"
|
||||
```
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass -e @vars-testing.yml
|
||||
```
|
||||
|
||||
## Environment-Specific Configurations
|
||||
|
||||
### Development Environment
|
||||
|
||||
```yaml
|
||||
# environments/dev.yml
|
||||
openclaw_install_mode: development
|
||||
openclaw_repo_url: "https://github.com/openclaw/openclaw.git"
|
||||
openclaw_repo_branch: "main"
|
||||
openclaw_ssh_keys:
|
||||
- "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"
|
||||
```
|
||||
|
||||
### Staging Environment
|
||||
|
||||
```yaml
|
||||
# environments/staging.yml
|
||||
openclaw_install_mode: release
|
||||
tailscale_authkey: "{{ lookup('env', 'TAILSCALE_AUTHKEY_STAGING') }}"
|
||||
openclaw_ssh_keys:
|
||||
- "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"
|
||||
```
|
||||
|
||||
### Production Environment
|
||||
|
||||
```yaml
|
||||
# environments/prod.yml
|
||||
openclaw_install_mode: release
|
||||
tailscale_authkey: "{{ lookup('env', 'TAILSCALE_AUTHKEY_PROD') }}"
|
||||
openclaw_ssh_keys:
|
||||
- "ssh-ed25519 AAAAC3... ops@prod-mgmt"
|
||||
- "ssh-ed25519 AAAAC3... admin@backup-server"
|
||||
nodejs_version: "22.x"
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### SSH Keys
|
||||
|
||||
1. **Use dedicated keys**: Create separate SSH keys for OpenClaw access
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -f ~/.ssh/openclaw_ed25519 -C "openclaw-access"
|
||||
```
|
||||
|
||||
2. **Limit key permissions**: Use SSH key options to restrict access
|
||||
```
|
||||
from="192.168.1.0/24" ssh-ed25519 AAAAC3... admin@trusted-network
|
||||
```
|
||||
|
||||
3. **Rotate keys regularly**: Update SSH keys periodically
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass \
|
||||
-e "openclaw_ssh_keys=['$(cat ~/.ssh/new_key.pub)']"
|
||||
```
|
||||
|
||||
### Tailscale Auth Keys
|
||||
|
||||
1. **Use ephemeral keys** for temporary access
|
||||
2. **Set expiration times** for auth keys
|
||||
3. **Use reusable keys** only for automation
|
||||
4. **Store in secrets manager**: Don't commit to git
|
||||
```bash
|
||||
# Use environment variable
|
||||
export TAILSCALE_AUTHKEY=$(vault read -field=key secret/tailscale)
|
||||
ansible-playbook playbook.yml --ask-become-pass \
|
||||
-e tailscale_authkey="$TAILSCALE_AUTHKEY"
|
||||
```
|
||||
|
||||
### Sensitive Variables
|
||||
|
||||
Never commit sensitive data to git:
|
||||
|
||||
```yaml
|
||||
# ❌ BAD - Don't do this
|
||||
tailscale_authkey: "tskey-auth-actual-key-here"
|
||||
|
||||
# ✅ GOOD - Use environment variables or vault
|
||||
tailscale_authkey: "{{ lookup('env', 'TAILSCALE_AUTHKEY') }}"
|
||||
|
||||
# ✅ GOOD - Use Ansible Vault
|
||||
tailscale_authkey: "{{ vault_tailscale_authkey }}"
|
||||
```
|
||||
|
||||
Create encrypted vault:
|
||||
```bash
|
||||
ansible-vault create secrets.yml
|
||||
# Add: vault_tailscale_authkey: tskey-auth-xxxxx
|
||||
|
||||
ansible-playbook playbook.yml --ask-become-pass \
|
||||
-e @secrets.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
After configuration, verify settings:
|
||||
|
||||
```bash
|
||||
# Check what variables will be used
|
||||
ansible-playbook playbook.yml --ask-become-pass \
|
||||
-e @vars.yml --check --diff
|
||||
|
||||
# View all variables
|
||||
ansible-playbook playbook.yml --ask-become-pass \
|
||||
-e @vars.yml -e "ansible_check_mode=true" \
|
||||
--tags never -vv
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### SSH Keys Not Working
|
||||
|
||||
Check file ownership and permissions:
|
||||
```bash
|
||||
sudo ls -la /home/openclaw/.ssh/
|
||||
sudo cat /home/openclaw/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
### Tailscale Not Connecting
|
||||
|
||||
Verify auth key is valid:
|
||||
```bash
|
||||
sudo tailscale up --authkey=YOUR_KEY --verbose
|
||||
```
|
||||
|
||||
### Installation Mode Issues
|
||||
|
||||
Check which mode is active:
|
||||
```bash
|
||||
ansible-playbook playbook.yml --ask-become-pass \
|
||||
-e @vars.yml --check | grep "install_mode"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Main README](../README.md)
|
||||
- [Development Mode Guide](development-mode.md)
|
||||
- [Upgrade Notes](../UPGRADE_NOTES.md)
|
||||
- [Defaults File](../roles/openclaw/defaults/main.yml)
|
||||
Reference in New Issue
Block a user