Deployment Overview of OpenClaw on Server¶

Prerequisites and Basic Requirements¶

The deployment of OpenClaw requires a Linux-based operating system, specifically Ubuntu, to ensure compatibility with the installation scripts and package managers. The following requirements must be met before initiating the installation:

• Operating System: Ubuntu (specific version not defined in source, but apt package manager is required).

• Privileges: Root access or sudo privileges are mandatory to install system packages, manage services, and configure the openclaw user.

• Required Packages: The installer automatically ensures the presence of ansible and git.

• Network Access: The server must have outbound internet access to clone the repository from GitHub and download Ansible collections.

File and Directory Structure¶

The OpenClaw application and its management tools are installed in a specific directory structure on the server. The primary installation directory and related paths are as follows:

• Installation Directory: /opt/openclaw-ansible

• Repository Source: https://github.com/openclaw/openclaw-ansible.git

• Branch: main

• Execution Script: /opt/openclaw-ansible/run-playbook.sh

• User Home Directory: /home/openclaw

Application Installation Process¶

The application is deployed using an automated installer script located within the cloned repository. The process involves cloning the repository, installing dependencies, and executing the main playbook.

1. Repository Cloning: The system clones the OpenClaw repository from https://github.com/openclaw/openclaw-ansible.git to /opt/openclaw-ansible, targeting the main branch.

2. Dependency Installation: The installer ensures ansible and git are present via apt. It then installs required Ansible collections using ansible-galaxy.

3. System Preparation: The installer stops unattended upgrades and waits for package managers (apt, dpkg) to be free to prevent conflicts during installation.

4. Execution: The installation is triggered by running the script ./run-playbook.sh from the /opt/openclaw-ansible directory.

   • The script runs with specific environment variables:

     • NODE_OPTIONS: --max-old-space-size=768

     • npm_config_jobs: 2

     • npm_config_loglevel: warn

     • CI: true

   • The installer includes a retry mechanism (3 retries with a 30-second delay) to ensure successful completion.

Access Rights and Security¶

The deployment creates a dedicated system user to manage the application and assigns specific group permissions.

• User Account: A user named openclaw is created with the following attributes:

  • Shell: /bin/bash

  • Password: Set to openclaw (hashed using sha512).

  • Groups: Added to the sudo group to allow administrative actions.

• Directory Ownership: The home directory /home/openclaw is recursively owned by the openclaw user and group.

• Script Permissions: The execution script run-playbook.sh is granted execute permissions for the user.

Permission Settings¶

File and directory permissions are configured to ensure the openclaw user has full control over their environment.

• Home Directory: The path /home/openclaw and all its contents are owned by openclaw:openclaw with recursive permissions applied.

• Installer Script: The file /opt/openclaw-ansible/run-playbook.sh has the execute bit set for the user (chmod u+x).

Starting, Stopping, and Updating¶

The primary method for managing the OpenClaw installation is through the provided playbook script.

• Installation/Update Command:

  cd /opt/openclaw-ansible
  ./run-playbook.sh
  

• Environment Variables: When running the script, the following environment variables are utilized by the installer:

  export NODE_OPTIONS="--max-old-space-size=768"
  export npm_config_jobs="2"
  export npm_config_loglevel="warn"
  export CI="true"
  

• Service Management: The installer interacts with the system's package manager and service control (systemctl) to manage unattended-upgrades, disabling them temporarily during installation and re-enabling them afterward.