Deployment Overview of OpenClaw on Server¶

Prerequisites and Basic Requirements¶

The deployment of OpenClaw requires a Linux environment with specific package dependencies and user privileges. The system must meet the following criteria:

Operating System: Ubuntu (verified via apt package manager).
Privileges: Root access or sudo privileges are required to install system packages and manage services.
Required Packages:
ansible
git
User Account: A dedicated system user named openclaw is created with a password and membership in the sudo group.
Package Management: The installer temporarily disables unattended-upgrades to prevent conflicts during the installation process and re-enables it upon completion.

File and Directory Structure¶

The application and its supporting files are organized within specific directories on the host system:

Installation Directory: /opt/openclaw-ansible
Contains the cloned repository from https://github.com/openclaw/openclaw-ansible.git.
Includes the execution script run-playbook.sh.
User Home Directory: /home/openclaw
Serves as the primary working directory for the openclaw user.
Contains user-specific configurations and environment variables.
Environment Configuration:
/home/openclaw/.profile: Configures the PNPM_HOME environment variable and updates the PATH.
/etc/environment: Updates the system-wide PATH to include OpenClaw binaries.
/etc/sudoers.d/openclaw-path: Configures secure_path and env_keep for the openclaw user to ensure pnpm binaries are accessible during sudo operations.

Application Installation Process¶

The OpenClaw application is installed via a script that clones the repository and executes the deployment logic. The process involves the following steps:

Repository Cloning: The system clones or updates the OpenClaw repository from the main branch into /opt/openclaw-ansible.
Dependency Installation: Ansible collections are installed using ansible-galaxy collection install -r requirements.yml.
Execution: The installation is triggered by running the script ./run-playbook.sh with elevated privileges.
Command: ./run-playbook.sh -e ansible_become=true
Working Directory: /opt/openclaw-ansible
Environment Variables: The installer runs with specific environment constraints to manage memory and concurrency:
NODE_OPTIONS: --max-old-space-size=768
npm_config_jobs: 2
npm_config_loglevel: warn
CI: true
PNPM_HOME: /home/openclaw/.local/share/pnpm
Retry Logic: The installation script includes a retry mechanism (up to 3 attempts with a 30-second delay) to ensure successful completion.

Access Rights and Security¶

Security configurations are applied to the openclaw user and the system environment:

User Creation: The openclaw user is created with /bin/bash as the default shell.
Group Membership: The user is added to the sudo group to allow administrative tasks.
Password: A password is set for the openclaw user using SHA512 hashing.
Sudo Configuration:
The secure_path is extended to include /home/openclaw/.local/share/pnpm/bin and /home/openclaw/.local/bin.
Environment variables PNPM_HOME and PATH are preserved during sudo execution.
Package Manager Locking: The installer includes logic to wait for apt, apt-get, dpkg, and unattended-upgrade processes to finish or terminate before proceeding, preventing file lock conflicts.

Permission Settings¶

File and directory permissions are strictly defined to ensure the application runs correctly:

Home Directory: /home/openclaw is owned by openclaw:openclaw with mode 0755.
Recursive Ownership: All files within /home/openclaw are recursively owned by the openclaw user and group.
Profile File: /home/openclaw/.profile is set to mode 0644 and owned by openclaw:openclaw.
Sudoers File: /etc/sudoers.d/openclaw-path is set to mode 0440 and owned by root:root.
Environment File: /etc/environment is set to mode 0644 and owned by root:root.
Execution Script: The run-playbook.sh script is granted execute permissions for the user (chmod u+x).

Starting, Stopping, and Updating¶

The deployment utilizes a specific script to manage the installation and update lifecycle.

Update/Run Command: To execute the deployment or update the application, run the following command from the installation directory:
```
cd /opt/openclaw-ansible
./run-playbook.sh -e ansible_become=true
```
Environment Context: The script relies on the openclaw user environment. Ensure that the PATH includes the pnpm binaries located in /home/openclaw/.local/share/pnpm/bin.
Post-Installation: After the installation completes, the unattended-upgrades service is re-enabled to maintain system security updates.