GTS WebChat docsby GTS Team

WebChat › Docs › Private server install

Private server install

Source: docs/private-server-install.md · USER

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:

curl -fLO https://gts-team.dev/downloads/webchat-private-relay.tar.gz
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_FILE_DOWNLOAD_REQUIRES_TOKEN=true
PCHAT_FREE_MODE_ENABLED=true
PCHAT_DEV_EXPOSE_CODES=false

# Optional: restrict who can log in to this private relay.
# Leave empty for an open relay.
# PCHAT_AUTH_ALLOWED_EMAILS=alice@example.com,bob@example.com
# PCHAT_AUTH_ALLOWED_DOMAINS=example.com

# Optional: grant relay-admin status after email login.
# Public relays should use exact admin email(s). Private relays may use emails or domains.
# PCHAT_ADMIN_EMAILS=owner@example.com
# PCHAT_ADMIN_DOMAINS=admins.example.com

PCHAT_FILE_DOWNLOAD_REQUIRES_TOKEN=true keeps uploaded file URLs private to signed-in users or to recipients who have the generated per-file token.

Relay admins can call /api/v1/webchat/admin/users with their X-PChat-Session token to list users and promote, block, or hide users on that relay.

If a user tries to log in with an email that is not allowlisted, the relay creates a pending access request and sends relay admins a WebChat message with Approve / Deny actions. Approved emails can then request the normal email code.

What it does not do yet:

  • It does not create the first admin automatically. Set PCHAT_ADMIN_EMAILS, then have that admin log in once so the relay has an admin WebChat address.
  • It does not email admins externally. Approval requests are delivered as WebChat messages to relay admins.
  • It does not notify admins who have never logged in on that relay.
  • It does not add password-only login. Approval allows the email; the user still verifies with the normal email code.
  • A denied user can request again later, which reopens the request as pending.

Optional user-to-user approval:

PCHAT_REQUIRE_NETWORK_APPROVAL=true

The default is open network mode: any allowed user on the relay can direct-message any other visible user. Set PCHAT_REQUIRE_NETWORK_APPROVAL=true for approval mode. In approval mode, unknown users cannot direct-message each other immediately. The first attempt creates a WebChat network request card for the recipient. After the recipient accepts, both sides can chat directly.

Configure SMTP for real email login codes:

EMAIL_ENABLED=true
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=webchat@example.com
SMTP_PASS=change-me
SMTP_FROM=webchat@example.com
SMTP_STARTTLS=true

Run

cd ..
WEBCHAT_RELAY_PORT=5110 ./start_relay.sh

Health check:

curl http://127.0.0.1:5110/health

Docker Install

Source Docker image:

curl -fLO https://gts-team.dev/downloads/webchat-private-relay.tar.gz
tar -xzf webchat-private-relay.tar.gz
cd webchat-private-relay
cp relay/.env.example relay/.env.local
# edit relay/.env.local, especially EMAIL_ENABLED and SMTP_* for login codes
mkdir -p relay/data relay/pchat_uploads

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/