Private server install

This guide is for shipping WebChat relay as a downloadable private server that users install on their own VPS, LAN machine, or cloud host.

Build A Download Package

Source package:

scripts/package_private_relay.sh

Output:

dist/webchat-private-relay/
dist/webchat-private-relay.tar.gz

Install On User Server

On the target server:

tar -xzf webchat-private-relay.tar.gz
cd webchat-private-relay/relay
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env.local

Edit:

relay/.env.local

Recommended public-server settings:

HOST=0.0.0.0
PORT=5110
BRIDGE_DB_PATH=./data/bridge.db
PCHAT_UPLOAD_DIR=./pchat_uploads
PCHAT_FREE_MODE_ENABLED=true
PCHAT_DEV_EXPOSE_CODES=false

Configure SMTP for real email login codes:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=webchat@example.com
SMTP_PASSWORD=change-me
SMTP_FROM=webchat@example.com

Run

cd ..
WEBCHAT_RELAY_PORT=5110 ./start_relay.sh

Health check:

curl http://127.0.0.1:5110/health

Docker Install

Source Docker image:

cp relay/.env.example relay/.env.local
mkdir -p relay/data relay/pchat_uploads
docker compose -f docker-compose.private-relay.yml up -d --build

server*.so. The runtime image does not copy server.py.

Connect WebChat GUI

In WebChat:

1. Open Settings.
2. Open Advanced relay, phone bridge, translation.
3. Select Private Server Relay.
4. Set Relay Server URL.
5. Save and login with email.

Share a launch link:

scripts/private_relay_link.py \
  --site https://your-webchat-site.example.com/app/webchat/chat.html \
  --relay https://relay.example.com

HTTPS

For public use, put the relay behind HTTPS with Caddy, Nginx, Cloudflare, or a load balancer:

https://relay.example.com -> http://127.0.0.1:5110

Persistence

Back up and persist:

relay/data/bridge.db
relay/data/relay_identity_ed25519.json
relay/pchat_uploads/