Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lDEVinux/eaglercraft/llms.txt

Use this file to discover all available pages before exploring further.

NGINX is optional but recommended for production deployments. It enables TLS (wss://), real IP forwarding for IP bans and rate limiting, security headers, and can serve the web client on the same domain as your server endpoint.

​
Installing NGINX

Open your terminal and run:
sudo apt update
sudo apt install nginx
To verify the installation, open any web browser and navigate to localhost. You should see the NGINX welcome page confirming it is running correctly.

​
Basic WebSocket Proxy Configuration

1

Navigate to the NGINX sites directory

cd /etc/nginx/sites-enabled
2

Create a configuration file named after your domain

Use your preferred editor to create a new file. For example:
nano eaglercraft.example.com
3

Paste the proxy configuration

Replace example.com with your actual domain and app_server_address with the ip:port of your EaglercraftBungee instance (e.g. 127.0.0.1:25565).
eaglercraft.example.com
server {
    listen 80;
    listen [::]:80;

    server_name example.com eaglercraft.example.com;
        
    location / {
        proxy_pass http://app_server_address;
        include proxy_params;
    }
}
4

Restart NGINX to apply changes

sudo service nginx restart
Your EaglercraftBungee server is now accessible through your domain.

​
Forwarding Real Client IPs

Forwarding the real client IP to EaglercraftBungee is required for IP bans and rate limiting to work correctly. Without it, all incoming connections appear to originate from 127.0.0.1. Step 1 — Add the header to your NGINX location block, directly below the proxy_pass line: 
proxy_set_header X-Real-IP $remote_addr;
Step 2 — Enable forward_ip in EaglercraftBungee’s config.yml:
config.yml
forward_ip: true
Without X-Real-IP forwarding, all connections appear from 127.0.0.1 and IP bans and rate limiting will not work. The default value of forward_ip in config.yml is false — you must explicitly set it to true after configuring the NGINX header.

​
Security Headers

Adding the following headers prevents players from using bookmarklets to load a client from a different URL onto your server page (cross-site scripting protection). Place these lines after the proxy_pass directive inside the location block: 
add_header X-Frame-Options "SAMEORIGIN";
add_header Referrer-Policy "strict-origin";
add_header X-XSS-Protection "1; mode=block";
add_header Content-Security-Policy "default-src 'self' 'unsafe-inline'; img-src 'self' 'unsafe-inline' data: blob:; connect-src 'self' ws: wss:; upgrade-insecure-requests";
These headers prevent players from bookmarklet-loading a different client from another URL onto your server page. The Content-Security-Policy header explicitly allows WebSocket connections (ws: and wss:) and inline assets while blocking external script sources.
A complete location block with all recommended settings looks like this:
eaglercraft.example.com
location / {
    proxy_pass http://127.0.0.1:25565;
    include proxy_params;

    proxy_set_header X-Real-IP $remote_addr;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header Referrer-Policy "strict-origin";
    add_header X-XSS-Protection "1; mode=block";
    add_header Content-Security-Policy "default-src 'self' 'unsafe-inline'; img-src 'self' 'unsafe-inline' data: blob:; connect-src 'self' ws: wss:; upgrade-insecure-requests";
}

​
Serving the Web Client

If you also want to host the Eaglercraft web client on the same domain, you can serve the stable-download/web/ folder using NGINX’s root directive. Keep the client files and the WebSocket endpoint on separate paths to avoid routing conflicts. For example, you might serve the client at https://eaglercraft.example.com/ using a root directive pointing to /var/www/html (where you’ve uploaded the contents of stable-download/web/), while the WebSocket proxy lives at https://eaglercraft.example.com/server:
eaglercraft.example.com
server {
    listen 80;
    listen [::]:80;

    server_name eaglercraft.example.com;

    root /var/www/html;
    index index.html;

    # Serve the web client at /
    location / {
        try_files $uri $uri/ =404;
    }

    # Proxy WebSocket connections to EaglercraftBungee
    location /server {
        proxy_pass http://127.0.0.1:25565;
        include proxy_params;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
See Hosting Your Own Eaglercraft Web Client for more details on uploading and configuring the client bundle.

Build docs developers (and LLMs) love

Get started for freeTalk to us