Self-Hosting & Configuration Guide (Linux)

This guide walks you through self-hosting Avalex on a Linux server (Ubuntu 22.04/24.04 LTS, Debian 12, or RHEL/CentOS). The Avalex server is distributed as a single, self-contained executable JAR that automatically serves both the high-performance REST API and the complete web administration portal UI. No separate frontend compilation, Node.js runtime, or static file hosting is required. All server behavior is controlled through the application.conf configuration file.

System Requirements

Operating System: Linux (Ubuntu 22.04/24.04 or Debian 12 recommended)
Runtime: OpenJDK 21 or Eclipse Temurin 21 JRE (java -version)
Database: MongoDB 6.0+ (MongoDB Atlas free cloud cluster or local instance)
Reverse Proxy: Nginx with Certbot (for custom domain & HTTPS)
Hardware: 1 vCPU, 1 GB RAM (handles thousands of validation requests per second)

1. Complete `application.conf` Configuration Reference

When starting Avalex, the server reads its configuration from application.conf. You can place this file in the same directory as your JAR, or point to it using -Dconfig.file=/path/to/application.conf. Here is the complete configuration file with all available settings:

# ==============================================================================
# Avalex Server Configuration (application.conf)
# ==============================================================================

# MongoDB Database Settings
mongodb {
  # MongoDB connection URI (Atlas cloud string or local mongodb://127.0.0.1:27017)
  uri = "mongodb+srv://user:password@cluster0.abcde.mongodb.net/?appName=Avalex"
  uri = ${?MONGODB_URI}

  # Database name
  database = "crm"
  database = ${?MONGODB_DATABASE}
}

# Network & HTTP Server Ports
http {
  # Network interface to bind to (use 127.0.0.1 when running behind Nginx)
  host = "127.0.0.1"
  host = ${?HTTP_HOST}

  # Backend REST API port
  port = 8080
  port = ${?HTTP_PORT}

  backend-port = ${http.port}
  backend-port = ${?HTTP_BACKEND_PORT}

  # Frontend Web Administration Portal UI port (served automatically by the JAR)
  site-port = 3000
  site-port = ${?HTTP_SITE_PORT}
}

# Pekko HTTP High-Performance Server Tuning
pekko {
  loglevel = "INFO"
  http {
    server {
      remote-address-header = on
      max-connections = 8192
      backlog = 1024
      tcp-keep-alive = on
      pipelining-limit = 16
      preview.enable-http2 = off
    }
  }
}

# JWT Token Signing Secret (Change this to a strong secret in production!)
jwt {
  secret = "replace-with-a-random-secure-64-character-jwt-signing-secret"
  secret = ${?JWT_SECRET}
}

# Master Super-Administrator Account
master-admin {
  username = "master"
  email = "master@yourdomain.com"
  password = "SetYourStrongMasterPasswordHere!"
  password = ${?MASTER_ADMIN_PASSWORD}
}

# BuiltByBit Integration Webhook (Optional)
builtByBit {
  # Secret key matching your BuiltByBit external license webhook settings
  secret = "your-builtbybit-secret-key"
  secret = ${?BUILTBYBIT_SECRET}
}

# Built-In Discord Bot (Optional)
discord {
  enabled = false
  enabled = ${?DISCORD_BOT_ENABLED}

  token = "YOUR_DISCORD_BOT_TOKEN_HERE"
  token = ${?DISCORD_BOT_TOKEN}
}

# License Key Auto-Generation Format
license {
  # Pattern format: 'X' is replaced with random alphanumeric characters
  format = "XXXX-XXXX-XXXX-XXXX"
  format = ${?LICENSE_FORMAT}
}

Configuration Keys Breakdown

Section & Key	Description	Default	Environment Variable Override
`mongodb.uri`	MongoDB connection URI	Required	`MONGODB_URI`
`mongodb.database`	Database name	`"crm"`	`MONGODB_DATABASE`
`http.host`	Host address to bind	`"127.0.0.1"`	`HTTP_HOST`
`http.backend-port`	REST API port	`8080`	`HTTP_PORT` / `HTTP_BACKEND_PORT`
`http.site-port`	Web Portal UI port	`3000`	`HTTP_SITE_PORT`
`jwt.secret`	Secret key for signing 7-day JWT tokens	Default dev secret	`JWT_SECRET`
`master-admin.username`	Master administrator username	`"master"`	—
`master-admin.password`	Master administrator password	`"change-me-now"`	`MASTER_ADMIN_PASSWORD`
`builtByBit.secret`	Shared secret for BuiltByBit webhooks	`""`	`BUILTBYBIT_SECRET`
`discord.enabled`	Enable the built-in Discord Bot	`false`	`DISCORD_BOT_ENABLED`
`discord.token`	Discord bot application token	`""`	`DISCORD_BOT_TOKEN`
`license.format`	License key generator pattern	`"XXXX-XXXX-XXXX-XXXX"`	`LICENSE_FORMAT`

2. Step-by-Step Linux Installation

Step 1: Install System Dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-21-jre-headless nginx certbot python3-certbot-nginx

Verify that Java 21 is installed:

java -version

Step 2: Database Setup

Avalex requires a MongoDB database.

MongoDB Atlas (Recommended): Create a free cluster at mongodb.com/atlas, whitelist your server IP, and copy the mongodb+srv://... URI.
Local MongoDB: Install mongodb-org via apt and start with sudo systemctl enable --now mongod.

Step 3: Deploy the JAR and Configuration

Create a dedicated application directory and system user:

sudo useradd -r -s /bin/false avalex
sudo mkdir -p /opt/avalex

Copy your avalex.jar and your customized application.conf into /opt/avalex/:

sudo cp avalex.jar /opt/avalex/avalex.jar
sudo nano /opt/avalex/application.conf

Set ownership and file permissions:

sudo chown -R avalex:avalex /opt/avalex
sudo chmod 600 /opt/avalex/application.conf

Step 4: Set Up Systemd Service (Auto-Start & 24/7 Uptime)

Create a systemd unit file so Avalex runs continuously in the background and restarts automatically on server reboot or crash:

sudo nano /etc/systemd/system/avalex.service

Paste the following service definition:

[Unit]
Description=Avalex Licensing & CRM Server
After=network.target

[Service]
Type=simple
User=avalex
Group=avalex
WorkingDirectory=/opt/avalex
ExecStart=/usr/bin/java -Xms256m -Xmx1024m -Dconfig.file=/opt/avalex/application.conf -jar /opt/avalex/avalex.jar
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now avalex

Check status and live logs:

sudo systemctl status avalex
sudo journalctl -u avalex -f

Step 5: Connect Custom Domain & HTTPS (Nginx)

Place the production Nginx configuration in /etc/nginx/sites-available/avalex.conf:

upstream avalex_backend {
    server 127.0.0.1:8080;
    keepalive 32;
}

upstream avalex_frontend {
    server 127.0.0.1:3000;
    keepalive 32;
}

server {
    listen 80;
    listen [::]:80;
    server_name license.yourdomain.com;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name license.yourdomain.com;

    ssl_certificate     /etc/letsencrypt/live/license.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/license.yourdomain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options SAMEORIGIN always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # Route API, Auth, License Validation, & Webhooks to Avalex Backend
    location ~ ^/(api|auth|staff|actions|licenses|customers|products|orders|roles|builtbybit|integrations|me) {
        proxy_pass http://avalex_backend;
        proxy_read_timeout 60s;
        proxy_connect_timeout 10s;
    }

    # Route Portal UI and static web assets to Avalex Frontend
    location / {
        proxy_pass http://avalex_frontend;
        proxy_read_timeout 60s;
        proxy_connect_timeout 10s;
    }
}

Enable the configuration and issue a free SSL certificate:

sudo ln -s /etc/nginx/sites-available/avalex.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d license.yourdomain.com

Open your browser and navigate to: https://license.yourdomain.com
Log in using your Master Admin credentials:
- Username: master (or configured master-admin.username)
- Password: (The password configured in master-admin.password)
Navigate to Staff & Roles > Registration Keys to generate single-use registration keys for your staff members.
Navigate to Products to create your software product catalog and define HWID and IP slot limits.

Get Started

Deployment

Core Concepts

Integration Guide

Administration Portal

Authentication

Self-Hosting Avalex on Linux

Self-Hosting & Configuration Guide (Linux)

System Requirements

1. Complete `application.conf` Configuration Reference

Configuration Keys Breakdown

2. Step-by-Step Linux Installation

Step 1: Install System Dependencies

Step 2: Database Setup

Step 3: Deploy the JAR and Configuration

Step 4: Set Up Systemd Service (Auto-Start & 24/7 Uptime)

Step 5: Connect Custom Domain & HTTPS (Nginx)

​Self-Hosting & Configuration Guide (Linux)

​System Requirements

​1. Complete application.conf Configuration Reference

​Configuration Keys Breakdown

​2. Step-by-Step Linux Installation

​Step 1: Install System Dependencies

​Step 2: Database Setup

​Step 3: Deploy the JAR and Configuration

​Step 4: Set Up Systemd Service (Auto-Start & 24/7 Uptime)

​Step 5: Connect Custom Domain & HTTPS (Nginx)

​3. First-Time Login & Initial Setup

Self-Hosting & Configuration Guide (Linux)

System Requirements

1. Complete `application.conf` Configuration Reference

Configuration Keys Breakdown

2. Step-by-Step Linux Installation

Step 1: Install System Dependencies

Step 2: Database Setup

Step 3: Deploy the JAR and Configuration

Step 4: Set Up Systemd Service (Auto-Start & 24/7 Uptime)

Step 5: Connect Custom Domain & HTTPS (Nginx)

3. First-Time Login & Initial Setup