> For the complete documentation index, see [llms.txt](https://esmp-fun.gitbook.io/plugins/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://esmp-fun.gitbook.io/plugins/community-chat/getting-started/relay-on-a-vps.md).

# Run the relay on a VPS

A VPS is a small rented Linux machine that's always on. It's the most reliable home for the relay: it doesn't depend on any one Minecraft server, so the network's chat stays up even while servers restart or move.

## What you need

* **Any small Linux VPS.** The relay is a \~23 MB jar that runs in \~256 MB of RAM, so the smallest plan anywhere is plenty: budget providers (RackNerd and friends) sell 1 GB boxes for $1–2/month on yearly deals, Hetzner's smallest is \~$4.50, and anything in between is fine. Pick **Ubuntu 24.04 or newer** (or Debian 13) as the operating system — the steps below assume it.
* **SSH access.** Your provider gives you an address plus a login — either `root` or a normal user with sudo rights (DigitalOcean and Hetzner give you `root`; AWS and Oracle give you a user called `ubuntu`). You log in from a terminal with `ssh root@YOUR-VPS-IP` (or `ssh ubuntu@...`). On Windows, PowerShell has `ssh` built in.
* **Your two files** — `ccsrv-relay.jar` (from your purchase) and the `config.yml` you made in [Set up the network](/plugins/community-chat/getting-started/set-up-the-network.md).

The commands below all start with `sudo`. If you're logged in as `root`, that's harmless — leave it in and everything still works.

## Step 1 — Install Java 25

Log in to the VPS and run:

```
sudo apt update
sudo apt install -y openjdk-25-jre-headless
java -version
```

The last command should print version 25 or higher. On Ubuntu 24.04+ and Debian 13 this package is right in the standard repositories. On an older system, use Eclipse Temurin's package repository instead — the copy-paste setup lives at [adoptium.net/installation/linux](https://adoptium.net/installation/linux) (three commands, then `sudo apt install temurin-25-jre`).

## Step 2 — Upload the two files

From a terminal **on your own PC** (not the VPS), in the folder where the files are:

```
scp ccsrv-relay.jar config.yml root@YOUR-VPS-IP:~
```

(Use your actual login user if it isn't `root`. On Windows, [WinSCP](https://winscp.net) does the same with drag-and-drop: connect to `YOUR-VPS-IP`, drop both files into the home folder.)

Back on the VPS, move them into a proper home:

```
sudo mkdir -p /opt/ccsrv
sudo mv ~/ccsrv-relay.jar ~/config.yml /opt/ccsrv/
```

## Step 3 — First start, by hand

```
cd /opt/ccsrv
sudo java -jar ccsrv-relay.jar
```

Within a few seconds you should see `Discord connected` and `Listening on ...`. If you get an error instead, the [troubleshooting page](/plugins/community-chat/help/troubleshooting.md) covers every common one. Press `Ctrl+C` to stop it again — the next step starts it properly.

## Step 4 — Keep it running forever

Make it a system service so it starts on boot and restarts if it ever crashes:

```
sudo useradd -r -s /usr/sbin/nologin ccsrv
sudo chown -R ccsrv /opt/ccsrv
```

Create the service file (`sudo nano /etc/systemd/system/ccsrv-relay.service`) with this content:

```ini
[Unit]
Description=CrossCommunitySRV relay
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ccsrv
WorkingDirectory=/opt/ccsrv
ExecStart=/usr/bin/java -Xms64m -Xmx256m --enable-native-access=ALL-UNNAMED -jar /opt/ccsrv/ccsrv-relay.jar /opt/ccsrv/config.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

Then:

```
sudo systemctl daemon-reload
sudo systemctl enable --now ccsrv-relay
```

Check on it any time with `systemctl status ccsrv-relay`, and watch its live log with `sudo journalctl -u ccsrv-relay -f`.

## Step 5 — Open port 8377

The Minecraft servers connect to the relay on port **8377** (TCP). Where to allow it depends on the provider — check each layer that applies to you:

* **The provider's cloud firewall** — most providers block everything but SSH by default and give you a firewall page in their web console. Hetzner calls it *Firewalls*, AWS *Security Groups*, Oracle *Security Lists / Network Security Groups*. Add an inbound rule: TCP, port 8377, source `0.0.0.0/0`.
* **A firewall on the VPS itself** — Ubuntu's `ufw` is *disabled* by default, so on most boxes there's nothing to do. If you enabled it: `sudo ufw allow 8377/tcp`.
* **Oracle Cloud only:** Oracle's Ubuntu images additionally ship with iptables rules baked into the machine that reject everything except SSH — and `ufw` won't help there. Edit `/etc/iptables/rules.v4`, duplicate the line that allows port 22, change the copy's port to 8377, make sure it sits **above** the REJECT line, then run `sudo netfilter-persistent reload`. (This bites almost everyone on Oracle's free tier — if the relay runs but nobody can connect, it's this.)

Quick test from your own PC once the relay is running:

```
curl -s -o /dev/null -m 5 http://YOUR-VPS-IP:8377 && echo reachable || echo blocked
```

`reachable` (or any instant response) means the port is open; five seconds of silence then `blocked` means a firewall in the list above is still in the way.

## Done

The relay is reachable at `ws://YOUR-VPS-IP:8377` — use that form to test from your own server. Then do the **last ten minutes** before handing anything out: [give the relay a domain address](/plugins/community-chat/getting-started/relay-behind-443.md). Many Minecraft hosts block their servers from making outbound connections to unusual ports like 8377, so the IP-and-port address works for some communities and silently times out for others — while `wss://crosschat.your-domain.com` (port 443) works from every host and encrypts the connection on top. That's the address to send out with the tokens ([Set up the network, Step 5](/plugins/community-chat/getting-started/set-up-the-network.md#step-5--hand-out-the-tokens)), pointing each community at [Connect a server](/plugins/community-chat/getting-started/connect-a-server.md).

To change the config later (add a community, tweak a setting): edit `/opt/ccsrv/config.yml`, then `sudo systemctl restart ccsrv-relay`. The restart takes seconds; servers reconnect on their own.