Client setup

Run the Ceili desktop client or build it from source.

Client setup

The Ceili client is a Wails desktop application with a React frontend. It connects to a Ceili chatserver over HTTP and WebSocket and keeps chat, room, voice, and diagnostics state in the client.

End-user setup

  1. Install a release build for your operating system.
  2. Enter the chatserver address, display name, and starting room.
  3. Confirm that the server is reachable at /healthz or /readyz if connection fails.
  4. Send a message, switch rooms, and join a voice channel to verify the connection.

The client connects to /ws?name=<display_name>&room=<room_id>. It preserves ws or wss semantics when converting an http or https server address. The client reconnects with exponential backoff after an unexpected disconnect and stores the last server, display name, and room locally.

Voice setup fetches /voice/bootstrap and targets the returned server peer ID, currently voice-sfu. The client uses hidden audio elements for remote playback and tears down peer connections, tracks, diagnostics loops, and injected audio elements when voice ends.

Developer prerequisites

  • Go 1.23 or later
  • Node.js 20 or later with npm
  • Wails CLI v2

Install the Wails CLI if needed:

go install github.com/wailsapp/wails/v2/cmd/wails@latest

Development

From the client directory, start the Wails development app:

wails dev

Build the frontend independently from the workspace:

npm.cmd --prefix c:\Docker\gabriel\client\frontend run build

Create a desktop production build:

wails build

Project boundaries

  • main.go and app.go define the root Wails entrypoint and lifecycle.
  • frontend/main.go and frontend/app.go define the frontend Wails entrypoint and lifecycle.
  • frontend/src/App.tsx orchestrates the main React application state.
  • frontend/src/services/chatSocket.ts owns WebSocket lifecycle and reconnect behavior.
  • frontend/src/types/protocol.ts contains the client-side protocol shapes.
  • Voice services own server bootstrap, signaling, media playback, diagnostics, and teardown.

The client must remain compatible with the server-relay protocol described in the API reference. It does not implement direct peer-to-peer mesh signaling.

Client debugging

The Debug tab exposes recent transport, state, replay, and protocol activity. Use lifecycle metadata and payload lengths when sharing logs; do not share raw SDP, ICE candidates, TURN credentials, or private chat content.