Server Setup Guide

1 Architecture Overview

OrngeChat Server is a single, self-contained executable with zero external dependencies. Everything is embedded:

PostgreSQL 16 — Relational database for users, guilds, channels, and metadata (port 5433)
Garnet — Microsoft's Redis-compatible in-memory cache for real-time messaging and SignalR backplane (port 6380)
LiteDB — Embedded NoSQL database for high-performance message document storage
LiveKit — Media server for voice channels and video calls (port 7880, auto-downloaded on first run)
LibreTranslate — Built-in translation engine (port 5100, auto-downloaded on first run)

All data is stored in the .orangechat-data folder next to the server executable. The only thing you need to provide is Nginx as a reverse proxy and an SSL certificate.

Port Summary

Internal ports (only accessible on localhost — Nginx proxies to these):
5000 HTTP • 5001 HTTPS • 7880 LiveKit WebSocket • 5433 PostgreSQL • 6380 Garnet • 5100 LibreTranslate

External ports (must be open on your firewall/router):
80 HTTP (for SSL cert renewal) • 443 HTTPS • 3478 UDP TURN • 50000–60000 UDP for WebRTC media

2 Prerequisites

Before setting up your OrngeChat server, make sure you have:

Operating System

Windows 10/11/Server 2019+ or Linux (Ubuntu 20.04+, Debian 11+, etc.)

Memory

4 GB RAM minimum, 8 GB recommended

Disk Space

1 GB minimum + space for uploads and databases

Network

Static IP or DDNS • Ports 80, 443, 3478 (UDP), 50000–60000 (UDP)

Port Forwarding Required

You need to forward these ports on your router to your server's local IP:
TCP 80 & 443 — Web traffic & SSL
UDP 3478 — TURN relay for voice/video behind NAT
UDP 50000–60000 — WebRTC media streams for voice & video calls
Search for your router model + "port forwarding" for specific instructions.

3 Getting a Domain Name

To serve OrngeChat over HTTPS you need a domain name pointing to your server's public IP. Here are your options:

Free Dynamic DNS (DDNS) Services

Perfect if you have a home connection with a changing IP address. These services automatically update your domain when your IP changes:

No-IP Free Tier

Popular DDNS with free subdomains. Requires monthly confirmation on the free plan.

noip.com

DuckDNS Free

Completely free, simple DDNS with subdomains under duckdns.org. No confirmation needed.

duckdns.org

Dynu Free Tier

Free DDNS with multiple domain options and good reliability.

dynu.com

FreeDNS (afraid.org) Free

Free DNS hosting with thousands of shared domains to choose from.

freedns.afraid.org

Paid Domain Registrars

For a professional setup with your own custom domain (recommended for communities):

GTXGaming Partnered Budget

Affordable domain registration with game server hosting. Great for gaming communities.

gtxgaming.co.uk

Cloudflare Registrar At Cost

Domains at wholesale prices with no markup. Includes free DNS and DDoS protection.

cloudflare.com

Namecheap Budget

Affordable domains with free privacy protection. Good selection of TLDs.

namecheap.com

Porkbun Budget

Very competitive prices with free WHOIS privacy. Simple and user-friendly interface.

porkbun.com

Setting Up DNS

Once you have a domain, create an A record pointing to your server's public IP address:

                        DNS Record
                        Type: A
Name: @ (or your subdomain, e.g., "chat")
Value: Your public IP address (e.g., 203.0.113.50)
TTL: 300 (or Auto)
                    

Find Your Public IP

Visit whatismyip.com to find your public IP address. If you're on a home connection, this may change periodically — consider using DDNS.

4 Download the Server

Download the OrngeChat server for your platform. The package includes everything needed to run your own instance:

Windows Server (.zip) Linux Server (.zip)

What's Included

OrngeChat.Server.exe (Windows) or OrngeChat.Server (Linux) — The main server executable
appsettings.json — Configuration file (ports, database settings, LiveKit, etc.)
wwwroot/ — The built-in web client files

Auto-Download Services

On first run, the server automatically downloads LiveKit (voice/video) and LibreTranslate (translation) binaries for your platform. This requires an internet connection on the first startup. Subsequent starts work offline.

5 Installation

Create a folder for the server:
C:\OrngeChat-Server
Extract the contents of OrngeChat-Server.zip into this folder.
Your folder should look like:
C:\OrngeChat-Server\ ├── OrngeChat.Server.exe ├── appsettings.json └── wwwroot\ ├── index.html └── assets\

Data Storage

On first run the server creates a .orangechat-data folder in the same directory containing all databases (PostgreSQL, Garnet, LiteDB), uploads, and auto-downloaded service binaries (LiveKit, LibreTranslate).

Create a directory and extract:
sudo mkdir -p /opt/orngechat sudo unzip OrngeChat-Server-Linux.zip -d /opt/orngechat
Make the binary executable:
sudo chmod +x /opt/orngechat/OrngeChat.Server
Create a dedicated user (recommended for security):
sudo useradd -r -s /bin/false orngechat sudo chown -R orngechat:orngechat /opt/orngechat
Your directory should look like:
/opt/orngechat/ ├── OrngeChat.Server ├── appsettings.json └── wwwroot/ ├── index.html └── assets/

Data Storage

On first run the server creates a .orangechat-data folder containing all databases, uploads, and auto-downloaded binaries. Make sure the orngechat user has write permission to /opt/orngechat.

6 Setting Up Nginx

Nginx acts as a reverse proxy — it receives all incoming traffic on ports 80/443 and forwards it to the OrngeChat server running on localhost:5000. It also handles SSL termination so your connections are encrypted.

Install Nginx

Download Nginx from nginx.org (use the Stable version .zip file).
Extract to C:\nginx
Your folder should contain:
C:\nginx\ ├── nginx.exe ├── conf\ │ └── nginx.conf ├── html\ └── logs\

Configure Nginx

Open C:\nginx\conf\nginx.conf and replace its entire contents with the following. This configures the reverse proxy for OrngeChat and LiveKit voice/video:

                            nginx.conf (Windows)
                            worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;
    client_max_body_size 25M;

    # Upstream to OrngeChat server
    upstream orngechat {
        server 127.0.0.1:5000;
    }

    # Upstream to LiveKit server (voice & video)
    upstream livekit {
        server 127.0.0.1:7880;
    }

    # HTTP — redirect everything to HTTPS
    server {
        listen       80;
        server_name  your-domain.com;

        # Let's Encrypt challenge directory
        location /.well-known/acme-challenge/ {
            root C:/nginx/html;
        }

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

    # HTTPS — main server + LiveKit
    server {
        listen       443 ssl;
        server_name  your-domain.com;

        ssl_certificate      C:/nginx/ssl/fullchain.pem;
        ssl_certificate_key  C:/nginx/ssl/privkey.pem;

        ssl_session_cache    shared:SSL:1m;
        ssl_session_timeout  5m;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers  HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers  on;

        # ── LiveKit WebSocket (voice & video) ──
        # Clients connect to wss://your-domain.com/rtc/
        location /rtc/ {
            proxy_pass http://livekit/;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            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 $scheme;
            proxy_read_timeout 86400s;
            proxy_send_timeout 86400s;
        }

        # ── OrngeChat app (API, web client, SignalR) ──
        location / {
            proxy_pass http://orngechat;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            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 $scheme;
            proxy_cache_bypass $http_upgrade;

            # WebSocket timeout (keeps SignalR alive)
            proxy_read_timeout 86400s;
            proxy_send_timeout 86400s;
        }
    }
}
                        

Test the Configuration

Open Command Prompt as Administrator and run:

cd C:\nginx && nginx -t

You should see syntax is ok and test is successful.

Install Nginx

                            Debian / Ubuntu
                            sudo apt update
sudo apt install nginx -y
                        

                            Fedora / RHEL
                            sudo dnf install nginx -y
                        

Configure Nginx

Create a new site configuration file. This configures the reverse proxy for OrngeChat and LiveKit voice/video:

sudo nano /etc/nginx/sites-available/orngechat

Paste the following:

                            /etc/nginx/sites-available/orngechat
                            # Upstream to OrngeChat server
upstream orngechat {
    server 127.0.0.1:5000;
}

# Upstream to LiveKit server (voice & video)
upstream livekit {
    server 127.0.0.1:7880;
}

# HTTP — redirect everything to HTTPS
server {
    listen 80;
    server_name your-domain.com;

    # Let's Encrypt / Certbot challenge directory
    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

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

# HTTPS — main server + LiveKit
server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    ssl_session_cache shared:SSL:1m;
    ssl_session_timeout 5m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    client_max_body_size 25M;

    # ── LiveKit WebSocket (voice & video) ──
    # Clients connect to wss://your-domain.com/rtc/
    location /rtc/ {
        proxy_pass http://livekit/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 $scheme;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }

    # ── OrngeChat app (API, web client, SignalR) ──
    location / {
        proxy_pass http://orngechat;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 $scheme;
        proxy_cache_bypass $http_upgrade;

        # WebSocket timeout (keeps SignalR alive)
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}
                        

Enable the Site

                            # Create symlink to enable the site
sudo ln -s /etc/nginx/sites-available/orngechat /etc/nginx/sites-enabled/

# Remove the default site (optional but recommended)
sudo rm /etc/nginx/sites-enabled/default

# Test the configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx
                        

Replace your-domain.com

Replace every instance of your-domain.com with your actual domain name in the Nginx configuration.

7 Nginx for LiveKit (Voice & Video)

The Nginx config above already includes the LiveKit proxy. Here's what's happening and why:

How LiveKit Routing Works

LiveKit handles voice channels and video calls using WebSocket signaling and WebRTC media streams. There are two network paths:

WebSocket signaling — Proxied through Nginx at /rtc/. This is the control channel where clients negotiate connections, join rooms, and receive participant updates. It goes through your SSL-secured Nginx.
WebRTC media streams — These carry the actual audio/video data and flow directly to the server over UDP ports 50000–60000, bypassing Nginx entirely. This is normal and required for low-latency voice/video.

Configure OrngeChat for the Proxy Path

Open appsettings.json and set the LiveKit Path so the server tells clients to connect through Nginx:

                        appsettings.json (LiveKit section)
                        "LiveKit": {
    "InternalPort": 7880,
    "Path": "/rtc/",
    "UseExternal": false,
    "AutoDownload": true,
    "RtcPortStart": 50000,
    "RtcPortEnd": 60000,
    "TurnEnabled": true,
    "TurnUdpPort": 3478,
    "LogLevel": "info"
}
                    

Key Setting: Path

The "Path": "/rtc/" setting tells the server to return WebSocket URLs like wss://your-domain.com/rtc/ to clients. This matches the location /rtc/ block in your Nginx config, so Nginx correctly forwards the connection to LiveKit on port 7880.

Firewall Rules for Voice/Video

Open PowerShell as Administrator and run:

                            PowerShell (Admin)
                            # Allow TURN relay (NAT traversal for voice/video)
New-NetFirewallRule -DisplayName "OrngeChat TURN" -Direction Inbound -Protocol UDP -LocalPort 3478 -Action Allow

# Allow WebRTC media ports (actual audio/video data)
New-NetFirewallRule -DisplayName "OrngeChat WebRTC" -Direction Inbound -Protocol UDP -LocalPort 50000-60000 -Action Allow
                        

If you're using ufw (common on Ubuntu/Debian):

                            UFW
                            # Allow TURN relay (NAT traversal for voice/video)
sudo ufw allow 3478/udp comment "OrngeChat TURN"

# Allow WebRTC media ports (actual audio/video data)
sudo ufw allow 50000:60000/udp comment "OrngeChat WebRTC"

# Reload
sudo ufw reload
                        

If you're using firewalld (common on Fedora/RHEL):

                            firewalld
                            sudo firewall-cmd --permanent --add-port=3478/udp
sudo firewall-cmd --permanent --add-port=50000-60000/udp
sudo firewall-cmd --reload
                        

Don't Forget Your Router

In addition to the OS firewall, you must also forward UDP 3478 and UDP 50000–60000 on your router to your server's local IP address. Without this, voice and video calls won't work for users outside your local network.

8 SSL with Let's Encrypt

Let's Encrypt provides free SSL certificates. The setup differs between Windows and Linux:

Install win-acme

Download win-acme from win-acme.com
Extract to C:\win-acme
Create the SSL directory:
mkdir C:\nginx\ssl

Obtain Certificate

Make sure Nginx is running (even HTTP-only is fine) before requesting a certificate:

Open Command Prompt as Administrator
Run the interactive wizard:
cd C:\win-acme && wacs.exe
Select N — Create certificate (default settings)
Select 2 — Manual input
Enter your domain name (e.g., chat.yourdomain.com)
For validation, select 1 — Save to path (http-01)
Enter the webroot path: C:\nginx\html
For certificate store, select 2 — PEM files
Enter the path: C:\nginx\ssl
Complete the wizard — certificates will be issued

Certificate Files

After issuance, you should have in C:\nginx\ssl:

fullchain.pem — Certificate chain (referenced in nginx.conf)
privkey.pem — Private key (referenced in nginx.conf)

Restart Nginx to apply SSL:

cd C:\nginx && nginx -s reload

Install Certbot

                            Debian / Ubuntu
                            sudo apt install certbot python3-certbot-nginx -y
                        

                            Fedora / RHEL
                            sudo dnf install certbot python3-certbot-nginx -y
                        

Obtain Certificate

Certbot will automatically configure Nginx for you:

sudo certbot --nginx -d your-domain.com

Follow the prompts to enter your email and agree to the terms. Certbot will:

Obtain the certificate from Let's Encrypt
Automatically update your Nginx configuration with the SSL paths
Set up automatic renewal via a systemd timer

Verify Auto-Renewal

sudo certbot renew --dry-run

Automatic Renewal

Both win-acme (Windows) and Certbot (Linux) automatically renew certificates before they expire. No manual intervention needed!

9 Running the Server

Quick Start

Make sure Nginx is running:
cd C:\nginx && start nginx
Start the OrngeChat server:
cd C:\OrngeChat-Server && OrngeChat.Server.exe
You should see output like:
[CONFIG] Kestrel configured: HTTP on :5000, HTTPS on :5001 HTTPS: https://localhost:5001 HTTP: http://localhost:5000 API: https://localhost:5001/swagger

Run as a Windows Service (Recommended for Production)

Use NSSM (Non-Sucking Service Manager) so OrngeChat starts automatically on boot:

Download NSSM from nssm.cc
Install OrngeChat as a service:
nssm install OrngeChat
In the NSSM dialog, set:
- Path: C:\OrngeChat-Server\OrngeChat.Server.exe
- Startup directory: C:\OrngeChat-Server
Start the service:
nssm start OrngeChat

Do the same for Nginx if you want it to start automatically as well.

Quick Start

cd /opt/orngechat && sudo -u orngechat ./OrngeChat.Server --console

The --console flag runs the server in the terminal (use Ctrl+C to stop).

Run as a systemd Service (Recommended for Production)

Create a service file so OrngeChat starts automatically on boot:

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

Paste the following:

                            orngechat.service
                            [Unit]
Description=OrngeChat Server
After=network.target

[Service]
Type=simple
User=orngechat
Group=orngechat
WorkingDirectory=/opt/orngechat
ExecStart=/opt/orngechat/OrngeChat.Server --console
Restart=always
RestartSec=10

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/opt/orngechat

[Install]
WantedBy=multi-user.target
                        

Enable and start the service:

                            sudo systemctl daemon-reload
sudo systemctl enable orngechat
sudo systemctl start orngechat
                        

Check the status:

sudo systemctl status orngechat

View logs in real-time:

sudo journalctl -u orngechat -f

Test Your Server

Open your browser and navigate to https://your-domain.com. You should see the OrngeChat login page!

10 Admin Setup

After starting your server, create an admin account to manage your instance.

Create Your First Account

Open your server URL in a browser (e.g., https://your-domain.com)
Click "Register" to create your account
Fill in your username, email, and password
Complete the encryption setup — save your recovery phrase!

Promote to Admin

The first user isn't automatically an admin. Promote your account using the command line:

Stop the server (Ctrl+C if running in console, or stop the service)
Run the promotion command using the email you registered with:
OrngeChat.Server.exe --promote-admin your-email@example.com
Restart the server

Stop the service:
sudo systemctl stop orngechat
Run the promotion command using the email you registered with:
sudo -u orngechat /opt/orngechat/OrngeChat.Server --promote-admin your-email@example.com
Restart the service:
sudo systemctl start orngechat

Once promoted, you'll have access to the admin panel at /admin where you can:

Manage users and permissions
View server statistics and analytics
Configure server settings
Moderate content and handle reports

11 Automated Installer (Optional)

If you'd rather skip all the manual steps above, you can use our automated installer scripts. These scripts handle everything — downloading the server, installing Nginx, obtaining SSL certificates, configuring LiveKit, and setting up the server as a system service.

Windows Installer (PowerShell)

Open PowerShell as Administrator and run:

irm https://api.orngechat.site/install-server.ps1 | iex

What it does:

Downloads and extracts OrngeChat Server to C:\OrngeChat-Server
Downloads and extracts Nginx to C:\nginx
Asks for your domain name and configures Nginx (with LiveKit proxy)
Downloads win-acme and obtains a Let's Encrypt SSL certificate
Sets the LiveKit Path in appsettings.json
Opens firewall ports (80, 443, 3478 UDP, 50000–60000 UDP)
Installs both as Windows services using NSSM (auto-start on boot)

Linux Installer (Bash)

Run as root or with sudo:

curl -fsSL https://api.orngechat.site/install-server.sh | sudo bash

What it does:

Downloads and extracts OrngeChat Server to /opt/orngechat
Creates a dedicated orngechat system user
Installs Nginx via your package manager
Asks for your domain name and writes the Nginx config (with LiveKit proxy)
Installs Certbot and obtains a Let's Encrypt SSL certificate
Sets the LiveKit Path in appsettings.json
Configures UFW or firewalld rules for voice/video
Creates and enables a systemd service (auto-start on boot)

Port Forwarding Still Required

The installer configures your OS firewall, but you still need to manually forward ports 80, 443, 3478 (UDP), and 50000–60000 (UDP) on your router. The installer cannot do this for you.

12 Troubleshooting

Certificate Issues

Let's Encrypt validation fails:

Ensure port 80 is accessible from the internet (check router port forwarding)
Check that your domain points to your public IP (nslookup your-domain.com)
Verify Nginx is running and the webroot/challenge path is correct
Check your OS firewall isn't blocking port 80

Connection Refused

If you can't connect to your server:

Check that both Nginx and OrngeChat.Server are running
Verify port forwarding on your router (80 and 443)
Check your OS firewall allows incoming connections
Test locally first: http://127.0.0.1:5000

WebSocket / SignalR Errors

If chat messages aren't working:

Ensure the Nginx config includes the Upgrade and Connection "upgrade" headers
Check that proxy_read_timeout is set to a high value (86400s)
Verify no intermediate proxies (like Cloudflare) are blocking WebSockets

Voice/Video Not Working

If voice channels or video calls fail:

Verify the /rtc/ location block exists in your Nginx config and proxies to port 7880
Check that "Path": "/rtc/" is set in appsettings.json under LiveKit
Ensure UDP ports 3478 and 50000–60000 are forwarded on your router and allowed by your OS firewall
Check the server logs for LiveKit errors: look for [LiveKit] in the console output
On first run, LiveKit needs to download its binary — make sure the server has internet access

Nginx Won't Start

Run nginx -t (Windows) or sudo nginx -t (Linux) to check for configuration errors
Check if another process is using port 80 or 443 (netstat -tlnp on Linux)
Ensure SSL certificate files exist at the configured paths
Check error logs: C:\nginx\logs\error.log (Windows) or /var/log/nginx/error.log (Linux)

Database Errors

OrngeChat uses an embedded PostgreSQL database. If you see database errors:

Ensure the server has write permissions to its directory and the .orangechat-data folder
Check that port 5433 isn't already in use by another PostgreSQL instance
Check server logs for specific error messages

Getting Help

Join the official OrngeChat server at app.orngechat.site and ask in the support channel
Check the GitHub repository for known issues

Contents

1 Architecture Overview

2 Prerequisites

3 Getting a Domain Name

Free Dynamic DNS (DDNS) Services

Paid Domain Registrars

Setting Up DNS

4 Download the Server

What's Included

5 Installation

6 Setting Up Nginx

Install Nginx

Configure Nginx

Test the Configuration

Install Nginx

Configure Nginx

Enable the Site

7 Nginx for LiveKit (Voice & Video)

How LiveKit Routing Works

Configure OrngeChat for the Proxy Path

Firewall Rules for Voice/Video

8 SSL with Let's Encrypt

Install win-acme

Obtain Certificate

Certificate Files

Install Certbot

Obtain Certificate

Verify Auto-Renewal

9 Running the Server

Quick Start

Run as a Windows Service (Recommended for Production)

Quick Start

Run as a systemd Service (Recommended for Production)

Test Your Server

10 Admin Setup

Create Your First Account

Promote to Admin

11 Automated Installer (Optional)

Windows Installer (PowerShell)

What it does:

Linux Installer (Bash)

What it does:

12 Troubleshooting

Certificate Issues

Connection Refused

WebSocket / SignalR Errors

Voice/Video Not Working

Nginx Won't Start

Database Errors

Getting Help