> 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/hub-on-a-vps.md).

# Run the hub on a VPS

A VPS is a small rented Linux machine that's always on. It's the most reliable home for the hub: 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 hub 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** — `communitychat-hub.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 communitychat-hub*.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/communitychat
sudo mv ~/communitychat-hub*.jar /opt/communitychat/communitychat-hub.jar
sudo mv ~/config.yml /opt/communitychat/
```

The `*` in that first line is deliberate: if your file arrived with a version number in it, this catches it whatever the number is and puts it in place under one steady name. Every command from here on refers to that name, so they all work as written — and when you update later, you replace that one file and change nothing else.

## Step 3 — First start, by hand

```
cd /opt/communitychat
sudo java -jar communitychat-hub.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 communitychat
sudo chown -R communitychat /opt/communitychat
```

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

```ini
[Unit]
Description=CommunityChat hub
After=network-online.target
Wants=network-online.target

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

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

Then:

```
sudo systemctl daemon-reload
sudo systemctl enable --now communitychat-hub
```

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

## Step 5 — Open port 8377

The Minecraft servers connect to the hub 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 hub runs but nobody can connect, it's this.)

Quick test from your own PC once the hub 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 hub 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 hub a domain address](/plugins/community-chat/getting-started/hub-domain-address.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://cchat.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/communitychat/config.yml`, then `sudo systemctl restart communitychat-hub`. The restart takes seconds; servers reconnect on their own.