141 lines
4.1 KiB
Markdown
141 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
CHGRID_HOST_ORIGIN=https://example.com
|
|
```
|
|
|
|
The expected env shape is also shown in [server/.env.sample](/home/jjm/code/chgrid/server/.env.sample).
|
|
|
|
## 3) Publish Client
|
|
|
|
```bash
|
|
cd "$REPO_ROOT"
|
|
./deploy/scripts/deploy_client.sh "$REPO_ROOT" "$PUBLISH_DIR" "$BASE_PATH"
|
|
```
|
|
|
|
## 4) Install/Reload Service Unit
|
|
|
|
```bash
|
|
cd "$REPO_ROOT"
|
|
./deploy/scripts/install_service.sh "$REPO_ROOT" "$UNIT_NAME"
|
|
```
|
|
|
|
Service logs:
|
|
|
|
```bash
|
|
journalctl -u "$UNIT_NAME" -f
|
|
tail -f "$REPO_ROOT/server/runtime/server.log"
|
|
```
|
|
|
|
## 5) One-Command Update
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd "$REPO_ROOT"
|
|
./deploy/scripts/install_apache.sh "$REPO_ROOT" /path/to/apache/include/chgrid.conf
|
|
```
|
|
|
|
Expected proxy endpoints:
|
|
|
|
```apache
|
|
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:
|
|
|
|
```apache
|
|
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, and the proxy reuses `CHGRID_HOST_ORIGIN` for its internal auth check.
|
|
|
|
If you deploy the PHP proxy some other way, you can still provide `CHGRID_HOST_ORIGIN` directly through your PHP/web-server environment.
|
|
|
|
Use:
|
|
|
|
```text
|
|
https://example.com/chgrid/media_proxy.php?url=urlencoded_upstream_url
|
|
```
|
|
|
|
## 9) Git Update Flow
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
git config --global credential.helper store
|
|
```
|
|
|
|
Then run one authenticated pull/push and enter:
|
|
- Username: your GitHub username
|
|
- Password: your GitHub PAT
|