Commonwealth-Online-Server/server/README.md

Commonwealth Online Server - Quick Start

Standalone dedicated relay server. No Qt/Host GUI build is required.

Quick Launch

Windows

Double-click start.bat, or run it from a terminal:

start.bat

Linux / macOS

chmod +x start.sh fix-port.sh   # recovery step if the executable bit was lost
./start.sh

The start script will:

1. Check that Python 3.9+ is installed
2. Create a local .venv virtual environment (never installs into the OS Python)
3. Install dedicated-server dependencies from requirements-server.txt when needed
4. Generate a default commonwealth-server.json config file (if needed)
5. Start consumer_server_cli.py listening on 0.0.0.0:7777 by default
6. Open an interactive commonwealth> prompt when stdin/stdout are a real terminal

At the prompt you can type commands directly, for example:

help
users
users once
ban 2 --reason griefing
world time 1430
quit

users live-updates the player table every second (press Enter to stop).

Update dependencies explicitly when needed:

./start.sh --update-dependencies

--update-dependencies is consumed by the start script and is not forwarded to the server.

If a file manager “Open with” passes commonwealth-server.json as an argument, start.sh treats that path as the config file and still launches with --config (it is not forwarded as a bare positional argument).

---

Linux Installation

Do not run sudo ./start.sh. Do not use pip install --break-system-packages. The script creates .venv automatically and invokes .venv/bin/python directly. Fish users do not need to activate anything.

Ubuntu and Debian

sudo apt install python3 python3-venv
chmod +x start.sh
./start.sh

Arch Linux and CachyOS

sudo pacman -S --needed python
chmod +x start.sh
./start.sh

Fedora

sudo dnf install python3
chmod +x start.sh
./start.sh

Firewall and networking

• Allow TCP 7777 (or your configured game port) through the host firewall.
• LAN discovery uses UDP 7778. If discovery is blocked, clients can still connect directly by IP/port.
• The admin channel binds to 127.0.0.1:7779 and should stay localhost-only.
• Router port forwarding is only needed when hosting behind a home router for outside connections.
• VPS users normally only need the provider firewall and OS firewall configured.
• 0.0.0.0 is a bind address, not the address clients should enter.
• Direct connections still work if LAN discovery is unavailable.

Example firewall openings:

# firewalld
sudo firewall-cmd --add-port=7777/tcp --permanent
sudo firewall-cmd --add-port=7778/udp --permanent
sudo firewall-cmd --reload

# ufw
sudo ufw allow 7777/tcp
sudo ufw allow 7778/udp

systemd (optional)

1. Install the server files under /opt/commonwealth-online (or another path).
2. Create an unprivileged commonwealth user/group.
3. Run ./start.sh --update-dependencies once as that user to create .venv.
4. Copy and edit commonwealth-online.service.example:

sudo cp commonwealth-online.service.example /etc/systemd/system/commonwealth-online.service
sudo systemctl daemon-reload
sudo systemctl enable --now commonwealth-online
journalctl -u commonwealth-online -f

Manage a headless/systemd server from another shell with the admin CLI:

.venv/bin/python -u consumer_server_cli.py status
.venv/bin/python -u consumer_server_cli.py users
.venv/bin/python -u consumer_server_cli.py help

systemctl stop commonwealth-online sends SIGTERM and the server shuts down cleanly.

CRLF / executable-bit recovery

Git clones should keep LF endings for start.sh because of .gitattributes. If you extracted a ZIP on Windows or otherwise lost Unix permissions/line endings:

sed -i 's/\r$//' start.sh
chmod +x start.sh

Prefer .tar.gz Linux releases so the executable bit is retained.

---

First Run

On first run, a default commonwealth-server.json file is created in the server directory with these settings:

{
  "host": "0.0.0.0",
  "port": 7777,
  "server_name": "Commonwealth Online Server",
  "server_description": "",
  "max_players": 16,
  "log_verbosity": "info",
  "admin_port": 7779
}

Port Already in Use?

If you get an address-already-in-use error, the game port is already taken.

Option 1: Kill the blocking process

Run fix-port.bat (Windows) or ./fix-port.sh (Linux / macOS).

Option 2: Use a different port

Use the same helper and choose “Use a different port”, or edit commonwealth-server.json.

Customizing the Server

Edit commonwealth-server.json to customize:

• host: Bind address (default 0.0.0.0 for all interfaces)
• port: Game TCP port (default 7777)
• server_name: Display name
• server_description: Optional short description
• max_players: Metadata for client displays
• log_verbosity: debug, info, warning, or error
• admin_port: Localhost admin TCP port (default 7779)

Connecting Clients

Once the server is running:

• Local PC: Connect to 127.0.0.1:7777 (or your custom port)
• LAN: Connect to your PC's local IP (displayed on startup, e.g. 192.168.1.64:7777)
• Remote: Forward TCP 7777 on your router and use your public IP

Stopping the Server

Type quit at the commonwealth> prompt, or press Ctrl+C. Under systemd use systemctl stop commonwealth-online.

---

Dependencies

File	Purpose
requirements-server.txt	Dedicated CLI/headless server (typer, rich)
requirements-host-gui.txt	Optional Python PySide6 GUI (dev_server_app.py)
requirements.txt	Compatibility aggregate (includes PySide6)

Dedicated servers should install only requirements-server.txt. The Windows Qt Host GUI wraps this CLI and does not need PySide6.

---

For Advanced Users (Command Line)

cd server
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-server.txt

# Generate config
.venv/bin/python -u consumer_server_cli.py config init my-config.json

# Start server with interactive prompt (same as start.sh on a TTY)
.venv/bin/python -u consumer_server_cli.py serve --config my-config.json --interactive

# Start server without a prompt (Host GUI / systemd / headless)
.venv/bin/python -u consumer_server_cli.py serve --config my-config.json

# Management commands from another terminal while a server is running
.venv/bin/python -u consumer_server_cli.py help
.venv/bin/python -u consumer_server_cli.py status
.venv/bin/python -u consumer_server_cli.py users
.venv/bin/python -u consumer_server_cli.py world time 1430
.venv/bin/python -u consumer_server_cli.py world weather 0002b52a

Run .venv/bin/python -u consumer_server_cli.py --help to see all available commands.

Troubleshooting: Port in Use

.venv/bin/python -u consumer_server_cli.py serve --config commonwealth-server.json --port 8000