Deployment Overview of OpenClaw on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the following system requirements must be met:

• Operating System: Debian 11+ or Ubuntu 20.04+.

• Privileges: Root or sudo access is required for package installation and service management.

• Network Ports:

• 80/tcp (HTTP) for Let's Encrypt validation and redirection.

• 443/tcp (HTTPS) for secure web panel access.

• 18789/tcp (Gateway Port) for internal application communication.

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a specific subdomain generated based on the server ID.

File and Directory Structure¶

The following directories are used for configuration, application data, and SSL certificates:

• /home/openclaw: Home directory for the openclaw user.

• /home/openclaw/.openclaw: Application configuration directory.

• /data/nginx: Nginx configuration and certificate management files.

• /data/nginx/user_conf.d: Custom Nginx reverse proxy configurations.

• /root/nginx: Docker Compose deployment files for the proxy.

Application installation process¶

The installation of OpenClaw involves several stages to set up the runtime environment, the application itself, and the secure web proxy:

1. System Preparation: The system is updated, and base packages (ca-certificates, curl, gnupg, sudo, dbus-user-session) are installed.

2. Runtime Environment Setup:

3. A dedicated user named openclaw is created with a home directory.

4. NodeSource repositories are added to provide the required Node.js runtime (version 24 or higher).

5. pnpm is installed globally via npm.

6. Application Installation: The OpenClaw application is installed globally for the openclaw user using pnpm install -g openclaw@latest.

7. Onboarding and Configuration:

8. An automated onboarding process is executed to initialize the local gateway.

9. A configuration patch is applied to the OpenClaw gateway to enable HTTPS reverse proxy support, allowing it to trust the Nginx proxy located on 127.0.0.1.

10. Proxy Setup: Docker and Certbot are configured to manage SSL certificates via Let's Encrypt, providing a secure entry point for the web panel.

Access Rights and Security¶

• User Isolation: The application runs under a dedicated openclaw user with restricted permissions.

• Firewall Configuration: If ufw is present on the system, rules are automatically added to allow incoming traffic on ports 80 and 443.

• Service Hardening: The OpenClaw gateway is managed as a systemd service with specific environment variables and restricted paths.

Databases¶

The application uses an internal data management approach; no external database connection parameters are required for the standard installation.

Docker Containers and Their Deployment¶

The deployment utilizes one primary container to handle SSL termination and reverse proxying:

Nginx-Certbot Container

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

• Ports: Listens on host ports 80 and 443.

• Volumes:

• nginx_secrets:/etc/letsencrypt (Certificates)

• /data/nginx/user_conf.d:/etc/nginx/user_conf.d (Proxy configurations)

• Environment Variables: CERTBOT_EMAIL is used for Let's Encrypt notifications.

• Restart Policy: unless-stopped

Custom Scripts and Additional Setup¶

The installation performs several non-standard configuration steps to ensure seamless HTTPS operation:

• Gateway Token Management: A unique gateway token is generated and stored in /root/openclaw-gateway-token.txt. This token is used for secure communication between the proxy and the application.

• Systemd Integration: A custom systemd unit file (openclaw-gateway.service) is created to manage the OpenClaw gateway as a background service.

• Configuration Patching: The application's internal configuration is modified via openclaw config patch to allow it to operate behind an HTTPS reverse proxy, specifically setting the publicOrigin and trustedProxies.

Application Update Instructions¶

To update the main OpenClaw application:

1. The installation script/process should be re-run to pull the latest version via pnpm.

2. Alternatively, if manual updates are performed, ensure the openclaw user is used and the gateway service is restarted after the update.

Location of configuration files and data¶

• Application Config: /home/openclaw/.openclaw

• Nginx Proxy Configs: /data/nginx/user_conf.d/

• SSL Certificates: Managed within the nginx_secrets Docker volume.

Available ports for connection¶

• Web Panel (HTTPS): 443 via the configured FQDN.

• Internal Gateway: 18789 (accessible locally).

Starting and Stopping the application¶

The OpenClaw gateway is managed as a systemd service:

• Start/Restart the gateway:

  sudo systemctl restart openclaw-gateway.service
  

• Stop the gateway:

  sudo systemctl stop openclaw-gateway.service
  

• Check status:

  sudo systemctl status openclaw-gateway.service
  

Proxy Servers¶

The application uses an Nginx container managed by Docker to act as a reverse proxy. This setup handles:

• SSL/TLS termination via Let's Encrypt.

• Automatic HTTP to HTTPS redirection.

• WebSocket support (via Upgrade and Connection headers) for real-time communication.

• Proxying requests from the public domain to the local OpenClaw gateway on port 18789.