> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancestraldev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting Avalex on Linux

> Complete step-by-step guide to installing and self-hosting Avalex on Linux.

# 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:

```hocon theme={null}
# ==============================================================================
# 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

```bash theme={null}
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:

```bash theme={null}
java -version
```

***

### Step 2: Database Setup

Avalex requires a MongoDB database.

* **MongoDB Atlas (Recommended)**: Create a free cluster at [mongodb.com/atlas](https://www.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

1. Create a dedicated application directory and system user:
   ```bash theme={null}
   sudo useradd -r -s /bin/false avalex
   sudo mkdir -p /opt/avalex
   ```
2. Copy your `avalex.jar` and your customized `application.conf` into `/opt/avalex/`:
   ```bash theme={null}
   sudo cp avalex.jar /opt/avalex/avalex.jar
   sudo nano /opt/avalex/application.conf
   ```
3. Set ownership and file permissions:
   ```bash theme={null}
   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:

```bash theme={null}
sudo nano /etc/systemd/system/avalex.service
```

Paste the following service definition:

```ini theme={null}
[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:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable --now avalex
```

Check status and live logs:

```bash theme={null}
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`:

```nginx theme={null}
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:

```bash theme={null}
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
```

***

## 3. First-Time Login & Initial Setup

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.