Skip to content

Deployment Overview of Openclaw on Server

Prerequisites and Basic Requirements

The deployment of Openclaw requires a Linux server environment with specific system packages and user configurations. The following components must be present on the host system:

  • Operating System: Ubuntu or Debian-based distribution (implied by apt usage).

  • Privileges: Root access or sudo privileges are required for installation, service management, and firewall configuration.

  • System Packages: The following packages are installed or required:

  • ansible

  • ca-certificates

  • curl

  • dbus-user-session

  • git

  • sudo

  • Docker: Docker Engine must be installed and functional.

  • User Account: A dedicated system user named openclaw is created with a home directory at /home/openclaw.

  • Network: Ports 80 and 443 must be accessible for the reverse proxy. Port 18789 is used internally for the Openclaw Gateway.

FQDN of the Final Panel

The application is accessed via a Fully Qualified Domain Name (FQDN) structured as follows:

  • Domain Format: <prefix><Server ID>.hostkey.in

  • Prefix: openclaw

  • Zone: hostkey.in

  • Example: If the Server ID is 123, the domain would be openclaw123.hostkey.in.

  • Access Protocol: HTTPS (port 443) is enforced. HTTP (port 80) redirects to HTTPS.

File and Directory Structure

The deployment utilizes specific directories for configuration, data, and certificates. The structure is organized as follows:

  • Openclaw Installation Directory: /opt/openclaw-ansible

  • Contains the cloned repository from https://github.com/openclaw/openclaw-ansible.git.

  • Branch: main.

  • Openclaw User Home: /home/openclaw

  • Owned by user openclaw and group openclaw.

  • Contains application data and configuration.

  • Nginx Configuration Directory: /root/nginx

  • Contains compose.yml for the Nginx/Certbot container.

  • Nginx Data Directory: /data/nginx

  • /data/nginx/user_conf.d: Contains custom Nginx server block configurations.

  • /data/nginx/letsencrypt: Directory for Let's Encrypt challenge files.

  • /data/nginx/nginx-certbot.env: Environment variables for the Nginx container.

  • SSL Certificates: /etc/letsencrypt

  • Managed by the nginx_secrets Docker volume.

  • Certificates are stored in /etc/letsencrypt/live/<final_domain>/.

  • Gateway Token Storage: ~/.ansible/openclaw/gateway-<server_id>.token

  • Located in the home directory of the user running the deployment (typically /root).

Application Installation Process

The Openclaw application is installed via a script located in the /opt/openclaw-ansible directory. The process involves cloning the repository, installing dependencies, and running the installer.

  1. Repository Clone:

  2. The repository is cloned to /opt/openclaw-ansible using Git.

  3. Branch: main.

  4. Dependency Installation:

  5. Ansible collections are installed via ansible-galaxy collection install -r requirements.yml.

  6. Installer Execution:

  7. The script ./run-playbook.sh is executed with the -e ansible_become=true flag.

  8. Environment variables set during installation:

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

    • npm_config_jobs: 2

    • npm_config_loglevel: warn

    • CI: true

    • PNPM_HOME: /home/openclaw/.local/share/pnpm

  9. Onboarding Configuration:

  10. The openclaw onboard command is executed non-interactively with the following parameters:

    • --mode local

    • --auth-choice skip

    • --gateway-auth token

    • --gateway-token <TOKEN>

    • --gateway-port 18789

    • --gateway-bind loopback

    • --skip-bootstrap

    • --skip-skills

    • --skip-health

    • --accept-risk

  11. Configuration Patching:

  12. The gateway configuration is patched to enable HTTPS reverse proxy support, set trusted proxies, and define allowed origins for the Control UI.

Access Rights and Security

Security measures are implemented through user isolation, firewall rules, and token-based authentication.

  • User Isolation:

  • The Openclaw service runs under the dedicated openclaw user.

  • Lingering is enabled for the openclaw user via loginctl enable-linger openclaw.

  • Firewall (UFW):

  • If UFW is installed, ports 80 and 443 are allowed for TCP traffic.

  • The firewall is reloaded after rule changes.

  • Authentication:

  • The Openclaw Gateway uses token-based authentication.

  • The token is stored securely in /root/openclaw-gateway-token.txt with permissions 0600.

  • Tailscale authentication is disabled (allowTailscale: false).

  • Trusted Proxies:

  • The gateway trusts proxies at 127.0.0.1 and ::1.

Databases

The provided configuration data does not specify a dedicated database service (such as PostgreSQL or MySQL) for Openclaw. The application appears to store state and configuration locally within the /home/openclaw directory and uses the file system for token storage. No database connection strings or settings are present in the source files.

Docker Containers and Their Deployment

Docker is used to deploy the Nginx reverse proxy and Certbot for SSL certificate management.

  • Container Image: jonasal/nginx-certbot:6.2.0-nginx1.31.0

  • Deployment Method: Docker Compose

  • Compose File Location: /root/nginx/compose.yml

  • Network Mode: host

  • Volumes:

  • nginx_secrets (external volume) mounted to /etc/letsencrypt.

  • /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d.

  • /data/nginx/letsencrypt mounted to /var/www/letsencrypt.

  • Environment Variables:

  • CERTBOT_EMAIL: [email protected]

  • Additional variables are loaded from /data/nginx/nginx-certbot.env.

  • RENEWAL_INTERVAL: Set to 8d in the environment file.

  • Startup Command:

  • docker compose up -d executed in /root/nginx.

Proxy Servers

Nginx acts as a reverse proxy for the Openclaw Gateway, handling SSL termination and HTTP-to-HTTPS redirection.

  • Configuration File: /data/nginx/user_conf.d/<final_domain>.conf

  • HTTP Server Block:

  • Listens on port 80.

  • Serves Let's Encrypt challenge files from /var/www/letsencrypt.

  • Redirects all other traffic to HTTPS.

  • HTTPS Server Block:

  • Listens on port 443 with SSL enabled.

  • SSL Certificates:

    • Full Chain: /etc/letsencrypt/live/<final_domain>/fullchain.pem

    • Private Key: /etc/letsencrypt/live/<final_domain>/privkey.pem

    • Trusted Certificate: /etc/letsencrypt/live/<final_domain>/chain.pem

  • SSL Parameters:

    • DH Parameters: /etc/letsencrypt/dhparams/dhparam.pem

    • HSTS Header: max-age=31536000; includeSubDomains

  • Proxy Settings:

    • Proxies requests to http://127.0.0.1:18789.

    • HTTP Version: 1.1.

    • Headers: Upgrade, Connection, Host, X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-Port, X-Real-IP, X-Forwarded-For.

    • Timeouts: Read and send timeouts set to 3600 seconds.

    • Buffering: Disabled.

    • Redirects: Disabled.

Permission Settings

File and directory permissions are strictly defined to ensure security and proper operation.

Path Owner Group Mode Description
/root/nginx root root 0755 Nginx compose directory
/data/nginx root root 0755 Nginx data directory
/data/nginx/user_conf.d root root 0755 Nginx config directory
/data/nginx/letsencrypt/.well-known/acme-challenge root root 0755 Let's Encrypt challenge directory
/data/nginx/nginx-certbot.env root root 0644 Nginx environment file
/root/nginx/compose.yml root root 0644 Docker Compose file
/data/nginx/user_conf.d/<final_domain>.conf root root 0644 Nginx server block config
/home/openclaw openclaw openclaw 0755 Openclaw user home
/root/openclaw-gateway-token.txt root root 0600 Gateway token file
/etc/sudoers.d/openclaw-path root root 0440 Sudoers configuration
/etc/systemd/system/openclaw-gateway.service root root 0644 Systemd service file

Location of Configuration Files and Data

  • Openclaw Gateway Configuration: Managed via openclaw config patch and stored within the /home/openclaw directory.

  • Nginx Configuration: /data/nginx/user_conf.d/<final_domain>.conf

  • Docker Compose: /root/nginx/compose.yml

  • Environment Variables: /data/nginx/nginx-certbot.env

  • SSL Certificates: /etc/letsencrypt/live/<final_domain>/

  • Gateway Token: /root/openclaw-gateway-token.txt

Available Ports for Connection

  • Port 80 (HTTP): Used for Let's Encrypt challenges and redirection to HTTPS.

  • Port 443 (HTTPS): Primary access port for the Openclaw web interface via Nginx.

  • Port 18789: Internal port for the Openclaw Gateway. Bound to loopback (127.0.0.1) and not directly accessible from external networks.

Starting, Stopping, and Updating

The Openclaw Gateway is managed as a systemd service.

  • Service Name: openclaw-gateway.service

  • Start Service: 

    systemctl start openclaw-gateway.service

  • Stop Service: 

    systemctl stop openclaw-gateway.service

  • Restart Service: 

    systemctl restart openclaw-gateway.service

  • Enable on Boot: 

    systemctl enable openclaw-gateway.service

  • Check Status: 

    systemctl status openclaw-gateway.service

  • Reload Daemon: 

    systemctl daemon-reload

For the Nginx proxy container:

  • Start/Update: 

    cd /root/nginx
docker compose up -d

  • Check Status: 

    cd /root/nginx
docker compose ps

question_mark
Is there anything I can help you with?
question_mark
AI Assistant ×