Deployment Overview of OmniRoute on Server¶

Prerequisites and Basic Requirements¶

To successfully deploy OmniRoute, the server must meet the following requirements:

• Operating System: Ubuntu (tested and documented).

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

• Dependencies: ca-certificates and curl.

• Network/Ports:

• Port 80 (HTTP) - Required for SSL certificate challenges.

• Port 443 (HTTPS) - Required for secure web panel access.

• Internal ports used by the application: 20128, 20129, and 20132.

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

The application is accessible via a specific subdomain generated based on the server ID within the hostkey.in zone.

File and Directory Structure¶

The deployment utilizes the following directory structure for configuration and data persistence:

• /root/omniroute: Main application directory containing environment variables and Docker Compose files.

• /root/nginx: Configuration files for the Nginx reverse proxy.

• /data/nginx: User-defined Nginx configurations and SSL challenge directories.

• /data/nginx/user_conf.d: Specific site configuration files.

• /data/nginx/letsencrypt: Let's Encrypt certificate storage and ACME challenges.

Application Installation Process¶

The installation process follows these steps:

1. System Preparation: The system updates the package cache and installs ca-certificates and curl. Any legacy Docker repository configurations are removed to ensure a clean environment.

2. Docker Engine Installation: Docker is installed on the host system.

3. Application Setup:

4. A dedicated directory /root/omniroute is created.

5. An .env file is generated containing unique security keys: JWT_SECRET, API_KEY_SECRET, and STORAGE_ENCRYPTION_KEY.

6. The application configuration is deployed via a Docker Compose file.

7. Container Deployment: The application stack is pulled from the registry and started using docker compose up -d.

Access Rights and Security¶

• Firewall: If ufw (Uncomplicated Firewall) is present, rules are automatically added to allow TCP traffic on ports 80 and 443.

• Permissions: Application directories are set with restricted permissions (0750 or 0644) to ensure only the root user can access sensitive configuration files.

• Secrets Management: Sensitive credentials (JWT, API keys) are generated during installation and stored in a protected .env file with 0600 permissions.

Databases¶

The application uses Redis as a data store for session management or caching.

Docker Containers and Their Deployment¶

The deployment consists of three primary containers managed via Docker Compose:

OmniRoute Application¶

• Image: diegosouzapw/omniroute:latest

• Container Name: omniroute

• Ports:

• 127.0.0.1:20128 (Dashboard & OpenAI API)

• 127.0.0.1:20129 (Secondary API Listener)

• Environment Variables: Includes NODE_ENV, REDIS_URL, and memory limits calculated based on host RAM.

• Volumes: omniroute-data:/app/data

• Restart Policy: unless-stopped

Redis¶

• Image: docker.io/library/redis:8-alpine

• Container Name: omniroute-redis

• Command: redis-server --save 60 1 --loglevel warning

• Volumes: redis-data:/data

• Restart Policy: unless-stopped

Nginx Certbot Proxy¶

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

• Network Mode: host

• Volumes:

• nginx_secrets:/etc/letsencrypt

• /data/nginx/user_conf.d:/etc/nginx/user_conf.d

• /data/nginx/letsencrypt:/var/www/letsencrypt

• Purpose: Handles SSL termination and provides automated Let's Encrypt certificate renewal via Certbot.

Application Update Instructions¶

To update the OmniRoute application to the latest version, execute the following commands in the application directory:

cd /root/omniroute
docker compose pull
docker compose up -d

Location of Configuration Files and Data¶

• Application Environment: /root/omniroute/.env

• Nginx Site Config: /data/nginx/user_conf.d/{domain}.conf

• Docker Compose (App): /root/omniroute/compose.yml

• Docker Compose (Proxy): /root/nginx/compose.yml

Available Ports for Connection¶

Starting and Stopping the Application¶

The application is managed using Docker Compose.

To stop the application:

cd /root/omniroute
docker compose down

To start the application:

cd /root/omniroute
docker compose up -d