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

# HTTPS & Reverse Proxy Configuration

> Complete guide for configuring HTTPS, custom domains, and Nginx reverse proxying for Avalex.

# Domain & HTTPS Setup (Linux / Nginx)

When deploying your self-hosted **Avalex** instance on a Linux server, you can connect your custom domain name (e.g. `license.yourdomain.com` or `crm.yourdomain.com`) and secure all API and Admin Portal traffic with HTTPS.

This guide walks you through setting up an **Nginx** reverse proxy on Linux with automated, free SSL certificates via **Let's Encrypt / Certbot**.

***

## 1. Point Your Domain Name to Your Server

Before configuring Nginx, point your domain or subdomain to your Linux server's public IP address:

1. Log into your DNS provider (Cloudflare, Namecheap, GoDaddy, Porkbun, AWS Route 53, etc.).
2. Add an **`A` Record**:
   * **Name / Host**: `license` (for `license.yourdomain.com`) or `@` (for root domain `yourdomain.com`)
   * **Target / Value**: Your Linux server's public IPv4 address
   * **TTL**: Auto or 300 seconds

***

## 2. Install Nginx and Certbot

Connect to your Linux server via SSH and install Nginx and Certbot:

### Ubuntu / Debian:

```bash theme={null}
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx
```

### RHEL / Rocky Linux / AlmaLinux / CentOS:

```bash theme={null}
sudo dnf install -y epel-release
sudo dnf install -y nginx certbot python3-certbot-nginx
sudo systemctl enable --now nginx
```

***

## 3. Configure the Nginx Site

1. Create a new site configuration file in `/etc/nginx/sites-available/avalex.conf`:
   ```bash theme={null}
   sudo nano /etc/nginx/sites-available/avalex.conf
   ```
2. Paste the following production configuration, replacing `license.yourdomain.com` with your actual domain name:

```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;
}

# HTTP (Port 80) — Redirect all traffic to HTTPS + Let's Encrypt Challenge Support
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;
    }
}

# HTTPS (Port 443) — Reverse Proxy & SSL Termination
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name license.yourdomain.com;

    # SSL Certificates (managed automatically by Certbot in Step 4)
    ssl_certificate     /etc/letsencrypt/live/license.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/license.yourdomain.com/privkey.pem;

    # TLS Security
    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;

    # Security Headers
    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;

    # IP & Header Forwarding (Preserves true client IPs for license checks & rate limiting)
    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;

    # WebSocket Support
    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;
    }
}
```

3. Enable the site and test Nginx syntax:
   ```bash theme={null}
   sudo ln -s /etc/nginx/sites-available/avalex.conf /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl reload nginx
   ```

***

## 4. Obtain Free SSL Certificate via Certbot

Run Certbot to automatically issue and install your Let's Encrypt certificate:

```bash theme={null}
sudo certbot --nginx -d license.yourdomain.com
```

Follow the on-screen prompts. Certbot will verify your domain, install the certificates, and automatically configure renewal via a background systemd timer.

***

## 5. Verify Your Setup

Once configured:

* **Admin Portal UI**: Access your web dashboard securely at `https://license.yourdomain.com`.
* **License Validation API**: In your software applications, call `POST https://license.yourdomain.com/licenses/validate`.
* **BuiltByBit Webhook**: Set your BuiltByBit resource webhook URL to `https://license.yourdomain.com/builtbybit`.

All HTTP traffic will automatically upgrade to HTTPS, and client IP addresses will be passed transparently to Avalex for rate limiting and IP slot enforcement.


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