Installation

Install and verify the Ceili Go chatserver.

Installation

The chatserver is a Go service that can run directly or in a container. This page covers the minimum deployment and verification path. For environment variables and voice networking, see Configuration and Voice configuration.

Requirements

Before you begin, make sure you have:

  • Go 1.23+ for a source build, or Docker 24+ and Docker Compose v2 for a container deployment
  • A host or local machine with the configured TCP port reachable by clients
  • A UDP range available for voice when the SFU is enabled

1. Prepare the server

Create a working directory for the Ceili deployment and enter it:

git clone <chatserver-repository-url> chatserver
cd chatserver

The default listen address is 0.0.0.0:8081.

2. Configure the runtime

The server reads CHATSERVER_* environment variables. A minimal local configuration is:

cat <<'EOF' > .env
CHATSERVER_HOST=0.0.0.0
CHATSERVER_PORT=8081
CHATSERVER_VOICE_STUN_URLS=stun:stun.l.google.com:19302
EOF

See Configuration for all available settings. Public deployments should use TLS termination so clients connect through wss:// and should configure TURN and the voice UDP path where direct NAT traversal is not sufficient.

3. Start the server

Run the service from the repository:

go run ./cmd/server

For a container deployment, publish the configured TCP port and the configured voice UDP range. The exact image and compose file are deployment artifacts and must use the same CHATSERVER_* settings.

4. Verify the service

Check both health endpoints:

curl http://localhost:8081/healthz
curl http://localhost:8081/readyz

The expected responses are ok and ready. A client can then connect using:

ws://localhost:8081/ws?name=alice&room=general

5. Next steps

After the app is up, you can:

  • configure TLS and a public hostname
  • configure ICE/STUN/TURN and UDP exposure for voice
  • connect a desktop client and test room isolation
  • review the API reference and architecture

Production notes

For production deployments, you should also:

  • configure reverse proxy settings with HTTPS
  • expose only the configured TCP and voice UDP ports
  • use structured logs and avoid logging raw SDP, ICE candidates, or private message content
  • monitor health, readiness, reconnects, and voice setup failures

The separate userserver project is not required by this chatserver installation and is not integrated into the current client flow.