chat_grid/deploy

Deployment Guide

This guide is intentionally host-agnostic.

1) Choose Your Paths Once

Pick your own repo path, publish path, base URL path, and service name.

Example values:

REPO_ROOT=/srv/chgrid
PUBLISH_DIR=/var/www/html/chgrid
BASE_PATH=/chgrid/
UNIT_NAME=chat-grid.service

Use your own paths for your host.

2) Install Server Runtime

cd "$REPO_ROOT"
./deploy/scripts/install_server.sh "$REPO_ROOT"

What this sets up:

• Python venv under server/.venv
• server/config.toml (if missing)
• server/.env with CHGRID_AUTH_SECRET (if missing)
• server/run_server.sh (loads .env and starts server)
• first-run admin bootstrap prompt (if no admin exists)

Before starting the service, set CHGRID_HOST_ORIGIN in server/.env to the exact browser origin that will host Chat Grid, for example:

CHGRID_HOST_ORIGIN=https://example.com

The expected env shape is also shown in server/.env.sample.

3) Publish Client

cd "$REPO_ROOT"
./deploy/scripts/deploy_client.sh "$REPO_ROOT" "$PUBLISH_DIR" "$BASE_PATH"

4) Install/Reload Service Unit

cd "$REPO_ROOT"
./deploy/scripts/install_service.sh "$REPO_ROOT" "$UNIT_NAME"

Service logs:

journalctl -u "$UNIT_NAME" -f
tail -f "$REPO_ROOT/server/runtime/server.log"

5) One-Command Update

cd "$REPO_ROOT"
./deploy/scripts/up.sh "$REPO_ROOT" "$PUBLISH_DIR" "$BASE_PATH" "$UNIT_NAME"

6) Apache Websocket Proxy

Install your vhost include from the provided snippet:

cd "$REPO_ROOT"
./deploy/scripts/install_apache.sh "$REPO_ROOT" /path/to/apache/include/chgrid.conf

Expected proxy endpoints:

ProxyPass        /chgrid/ws  ws://127.0.0.1:8765/chgrid/ws
ProxyPassReverse /chgrid/ws  ws://127.0.0.1:8765/chgrid/ws
ProxyPass        /chgrid/auth/session/  http://127.0.0.1:8765/chgrid/auth/session/
ProxyPassReverse /chgrid/auth/session/  http://127.0.0.1:8765/chgrid/auth/session/

The websocket server enforces browser origin matching against CHGRID_HOST_ORIGIN, so the public site origin must match that env var exactly. The server.base_path value in config.toml must match the published client path and the proxy paths above.

What each route does:

• <base_path>ws: websocket signaling (presence, movement, item actions, chat, voice signaling).
• <base_path>auth/session/set: called by client after successful login to set the instance-scoped HttpOnly session cookie.
• <base_path>auth/session/clear: called by client on logout/session-reset to clear the instance-scoped HttpOnly session cookie.

After Apache changes, reload Apache using your host's command.

7) Optional HTTP Stream Relay

If you need HTTPS relays for plain HTTP streams, add vhost relays such as:

ProxyPass        /listen/8000/  http://127.0.0.1:8000/
ProxyPassReverse /listen/8000/  http://127.0.0.1:8000/

8) PHP Media Proxy

deploy/php/media_proxy.php is copied into your publish directory by deploy_client.sh.

When server/.env contains CHGRID_HOST_ORIGIN, deploy_client.sh also generates media_proxy.config.php in the publish directory so the proxy can enforce the same origin and validate authenticated sessions without extra Apache-specific config. The generated file derives the local auth-check URL from server/config.toml, so custom signaling ports continue to work.

If you deploy the PHP proxy some other way, you can still provide CHGRID_HOST_ORIGIN directly through your PHP/web-server environment.

Use:

https://example.com/chgrid/media_proxy.php?url=urlencoded_upstream_url

9) Git Update Flow

cd "$REPO_ROOT"
git fetch origin
git switch main
git pull --ff-only origin main
./deploy/scripts/install_server.sh "$REPO_ROOT"
./deploy/scripts/up.sh "$REPO_ROOT" "$PUBLISH_DIR" "$BASE_PATH" "$UNIT_NAME"

10) HTTPS Git Auth (PAT)

git config --global credential.helper store

Then run one authenticated pull/push and enter:

• Username: your GitHub username
• Password: your GitHub PAT