Server Quick Start

This page shows you how to set up your own server.

Note: Downloading the server requires a premium account.

Start a basic server
- Connecting to your server
- Troubleshooting
Command-line Options
Server Commands
Run a dedicated headless server
- Installation
Adding SSL
- Steps
Health checks

Start a basic server

Install Java 1.8 from here.
Open the game, then download the server from the main menu in the top right corner.
Open Command Prompt (Windows) / Terminal (Mac) then make sure it's set to the same folder where you downloaded the server.
Run this command to start the server: java -jar server-latest-obf.jar headless

Connecting to your server

Once the server is running there are a few ways you can connect to it.

Connecting to the server from the server list (Direct Connect)

You can join the server from the server list using the Direct Connect option.

Open the game
Click Servers
Click the Advanced checkbox
Click Direct Connect
Enter localhost:6768 and connect

Connecting directly from browser client

http://lurkers.io/client/latest/index.html?host=MY_SERVER_IP_ADDRESS
# Example:
https://lurkers.io/client/195/index.html?host=localhost&port=6768&secure=false

Note: Replace MY_SERVER_IP_ADDRESS with your IP address

Connecting directly from desktop client

Or using the desktop client, connect automatically from command line with:

java -jar desktop-latest-obf.jar dev host=localhost width=1200 height=800

Troubleshooting

I can't connect to the server.

Make sure there are no errors on the server.
Make sure you are connecting via HTTP instead of HTTPS.
Make sure your ports are open:
- 80: HTTP port
- 443: HTTPS port (optional)
- 6768: Default websocket port
- 6767: Default secure websocket port (optional)
- 22: SSH port (optional)
- 8849: JProfiler port (optional)
Try opening the browser Developer Tools and seeing if there are any errors there.

Command-line Options

Option	Description
headless	Runs without a graphical interface. Useful for running a dedicated server
port	Specifies what port to run on. Defaults to 6768
name	The name of the server
private	Skips registering to the master server. Note that your port must be accessible to do this anyways
nossl	Skips SSL if there is a `domain.cert.pem` (fullchain) and a `private.key.pem` file available
level	The name of the level to load. If the level does not exist, a new one will be created
script	Specify what script should be loaded. Defaults to the script found in the level config. You can provide your own Lua script here if placed adjacent to your `server.jar`
maxplayers	The maximum number of players that can join your server. Defaults to unlimited players
dev	Runs the server in development mode. Disables reporting analytics. Disables client AFK timeouts
nosandbox	Disables sandboxed Lua environment giving you full access to Lua globals such as `os`, `io`, `package`, `debug`, `file`. WARNING: May be a security risk if other players can run Lua commands or if your Lua environment is accessible to anyone else.
verbose	Enables additional logging to get a better idea of what the server is doing
version	Shows what version the server is running
customCertFilePath	Absolute file path override for SSL certificates.
customKeyFilePath	Absolute file path override for SSL certificates.
customIntermediateFilePath	Absolute file path override for SSL certificates.

Example command-line configuration for a test server:

java -jar server.jar dev headless name="MyCustomServer" private nossl script="zombie_survival.lua"

Server Commands

There are 3 ways to run server commands:

Run a server command from the CLI It's possible to enter commands from the command line of the server itself. Example: /schedulerestart 60 "Restarting server in 1 minute!"
Run a server command from the game chat As long as your player has permissions to run the command you can simply enter the command in chat. Example: /give dirt 30, or .give dirt 30
Run a server command from a script You can also run commands from a Lua script: Example: Game:runCommand("restart")

Run a dedicated headless server

We have a server setup script that sets up a dedicated server as a service. It is configured to run on Ubuntu 22.04. A Docker container may be released at some point if enough people ask for it. If you want to run a server all the time, it is useful to run your server as headless and set up a service so it will restart if it fails for some reason.

Installation

# install server setup
yum install wget -y
wget https://lurkers.io/wiki/server_setup.tar.gz
rm server_setup
mkdir server_setup
tar -xf server_setup.tar.gz -C .
rm -rf server_setup.tar.gz
chmod +x server_setup

# install server
sudo sh ./server_setup/server_setup_full.sh \
    --port 6768 \
    --securePort 6767 \
    --serverName "Lurkers Server" \
    --launchArgs "nossl headless name='Lurkers Server' port='6768'" \
    --serviceName lurkers-server \
    --build latest \
    --workingDir "/root"

Adding SSL

Note: The client must be using HTTPS for SSL to work. We recommend not using SSL for non-official servers, and instead having clients connect using HTTP since it's easier. However, web clients require https if they want to connect directly when playing on our official web platforms.

Clients connecting to your server through the server list will automatically be redirected to HTTP if the server is not using SSL. On browser / web builds, users will receive a prompt to manually redirect to http since browsers don't redirect to http by themselves.

Steps

Ensure you have a HTTPS web domain registered, for example https://lurkersisbest.com/. You will need it to redirect players to your server securely.
Create an A record DNS subdomain entry which points to your server IP address, for example https://mycoolserver.lurkersisbest.com > 123.45.67.89
Generate SSL certificates for your domain. Ensure it works against subdomains as well. You can validate your SSL certificate here: https://www.sslshopper.com/ssl-checker.html#hostname=mycoolserver.lurkersisbest.com:6787
Place the certificate files next to your server jar file. They must be called: domain.cert.pem (fullchain) and private.key.pem (private key). The server will automatically load them when it launches.
Set the secure address and port for your java server in the launch args: secureHost='mycoolserver.lurkersisbest.com' securePort='6768' secureHostKey='<INSERT_SECURE_HOST_KEY_HERE>' Replace INSERT_SECURE_HOST_KEY_HERE with the secure host key which is given to you by a developer (ask bergice on the Discord server).
You should now be able to connect securely via HTTPS/WSS to your server: wss://mycoolserver.lurkersisbest.com:6768

Health checks

You can call the /healthcheck websocket endpoint to perform a health check. The server will open the connection, then close it with a NORMAL response code and an OK message if the connection is successful.

lurkers.io Wiki