Deployment Overview of OmniRoute on Server¶

Prerequisites and Basic Requirements¶

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

• Operating System: Ubuntu (tested and documented).

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

• Network/Ports:

• 80/tcp (HTTP)

• 443/tcp (HTTPS)

• Dependencies: The system must have curl and ca-certificates installed.

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

The application is accessible via a specific subdomain generated using the server's unique identifier.

File and Directory Structure¶

The application uses the following directory structure for configuration, data, and SSL certificates:

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

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

• /data/nginx: User-defined Nginx configurations and Certbot renewal settings.

• /data/nginx/user_conf.d: Custom Nginx server block templates.

• /data/nginx/letsencrypt: Webroot for Let's Encrypt ACME challenges.

Application installation process¶

The application is deployed using a combination of package management and Docker:

1. System Preparation: The system updates the package cache and installs ca-certificates and curl.

2. Docker Installation: The Docker engine is installed on the host system.

3. Environment Setup:

4. A directory /root/omniroute is created with restricted permissions (0750).

5. An .env file is generated containing unique secrets for JWT_SECRET, API_KEY_SECRET, and STORAGE_ENCRYPTION_KEY.

6. Container Deployment: The application stack is deployed using Docker Compose from the /root/omniroute/compose.yml file.

Access Rights and Security¶

• Firewall: If UFW (Uncomplicated Firewall) is active, ports 80 and 443 are explicitly allowed to permit web traffic.

• Permissions:

• The application directory /root/omniroute is restricted to the root user (0750).

• Sensitive environment files (.env) are set with 0600 permissions.

• Network Isolation: Application ports (Dashboard and API) are bound to 127.0.0.1 to prevent direct external access, forcing all traffic through the Nginx reverse proxy.

Databases¶

The application utilizes Redis as a data store for session/state management:

Docker Containers and Their Deployment¶

The deployment consists of three main containers managed via Docker Compose.

Application Stack (OmniRoute Directory)¶

Redis Container

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

• Container Name: omniroute-redis

• Restart Policy: unless-stopped

• Volumes: redis-data:/data

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

OmniRoute Container

• Image: diegosouzapw/omniroute:latest

• Container Name: omniroute

• Restart Policy: unless-stopped

• Volumes: omniroute-data:/app/data

• Environment Variables:

• NODE_ENV: production

• DATA_DIR: /app/data

• OMNIRoute_MEMORY_MB: Dynamically calculated based on system RAM.

• REDIS_URL: redis://redis:6379

Proxy Stack (Nginx Directory)¶

Nginx Container

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

• Network Mode: host

• Restart Policy: unless-stopped

• Volumes:

• nginx_secrets (External volume): /etc/letsencrypt

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

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

Custom Scripts and Additional Setup¶

The deployment performs several automated configuration steps:

• Secret Generation: Generates high-entropy strings for JWT, API keys, and storage encryption.

• Host Configuration: Adds the final FQDN to the local /etc/hosts file pointing to 127.0.0.1.

• SSL Provisioning: Configures a reverse proxy with Certbot to automatically obtain and renew SSL certificates via Let's Encrypt.

Application Update Instructions¶

To update the main OmniRoute application, 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 Configuration: /root/omniroute/.env

• Nginx User Configs: /data/nginx/user_conf.d/[your-domain].conf

• Docker Volumes: Managed by Docker (typically under /var/lib/docker/volumes/).

Available ports for connection¶

The following ports are used internally and proxied via Nginx:

Starting and Stopping the application¶

Management of the application stack is performed via Docker Compose:

• Start Application:

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

• Stop Application:

  cd /root/omniroute && docker compose down