Skip to content

Deployment Overview of OpenClaw on Server

Prerequisites and Basic Requirements

To ensure a successful deployment, the following 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.

  • Ports: The following ports must be open in the firewall (e.g., UFW):

  • 80/tcp (HTTP)

  • 443/tcp (HTTPS)

  • 18789/tcp (OpenClaw Gateway - internal use/loopback).

FQDN of the final panel on the hostkey.in domain

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

Parameter Value
Prefix openclaw
Domain hostkey.in
Full template openclaw{Server_ID_from_Invapi}.hostkey.in

File and Directory Structure

The application uses several directories for configuration, data, and system services:

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

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

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

  • /data/nginx/user_conf.d: Custom Nginx virtual host configurations.

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

  • /etc/systemd/system/openclaw-gateway.service: Systemd service unit file.

Application installation process

The installation follows a multi-stage process to set up the environment, the application runtime, and the web server:

  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 settings to enable HTTPS reverse proxy support, allowing it to trust the Nginx proxy.

  10. Reverse Proxy Setup: Docker and Certbot are configured to manage SSL certificates via Let's Encrypt and provide an Nginx reverse proxy.

Access Rights and Security

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

  • Firewall Configuration: UFW is configured to allow incoming traffic on ports 80 and 443.

  • Service Hardening: The OpenClaw Gateway service is managed by systemd with specific environment variables and security limits (e.g., OOMPolicy=continue).

  • Token Security: A unique gateway token is generated and stored securely in /root/openclaw-gateway-token.txt for administrative access.

Databases

The application uses a local SQLite database as part of its default configuration, which is managed internally by the OpenClaw process. 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 web traffic:

Nginx-Certbot Container

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

  • Network Mode: host

  • Volumes:

  • nginx_secrets:/etc/letsencrypt (SSL certificates)

  • /data/nginx/user_conf.d:/etc/nginx/user_conf.d (Nginx configuration files)

  • Environment Variables:

  • CERTBOT_EMAIL: The contact email for SSL certificate notifications.

  • Restart Policy: unless-stopped

Custom Scripts and Additional Setup

Several non-standard actions are performed to ensure the application functions correctly in a proxied environment:

  • Configuration Patching: A JSON5 configuration patch is applied to the OpenClaw gateway to configure publicOrigin, controlUi origins, and trustedProxies.

  • Systemd Integration: A custom systemd service (openclaw-gateway.service) is created to manage the application as a background daemon, including logic to clean up orphaned processes on port 18789 during startup/shutdown.

  • Environment Persistence: Lingering is enabled for the openclaw user to ensure services remain running after logout.

Application Update Instructions

To update the OpenClaw application:

  1. The application should be updated via the global package manager used during installation:

    pnpm install -g openclaw@latest
    

  2. After updating the binary, the openclaw-gateway service must be restarted to apply changes:

    sudo systemctl restart openclaw-gateway.service
    

Location of configuration files and data

Component Path
OpenClaw Config Directory /home/openclaw/.openclaw
Nginx User Configs /data/nginx/user_conf.d
Gateway Environment File /home/openclaw/.openclaw/gateway.env
SSL Certificates /etc/letsencrypt/live/{domain}/ (inside container)

Available ports for connection

  • HTTPS: 443 (via Nginx proxy).

  • HTTP: 80 (redirects to HTTPS).

  • Internal Gateway: 18789 (local loopback only).

Starting and Stopping the application

The OpenClaw Gateway is managed via systemctl:

  • Start the application:

    sudo systemctl start openclaw-gateway.service
    

  • Stop the application:

    sudo systemctl stop openclaw-gateway.service
    

  • Check status:

    sudo systemctl status openclaw-gateway.service
    

Proxy Servers (Nginx, Traefik, SSL, custom domains)

The application uses an Nginx container acting as a reverse proxy with Certbot for automated SSL management.

  • SSL/TLS: Certificates are obtained via Let's Encrypt and managed through the nginx-certbot Docker image.

  • Reverse Proxy Logic: Nginx listens on ports 80 and 443, handles ACME challenges in /var/www/letsencrypt, and proxies all other traffic to http://127.0.0.1:18789. It is configured with specific headers (X-Forwarded-Proto, Upgrade, etc.) to support WebSockets and secure communication.

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