# PoliticTalk Jitsi Setup

This folder is the local source of truth for the PoliticTalk Jitsi setup used by:

```text
https://politictalk.parallelglobe.io
```

The VPS still runs the actual Jitsi services. Changes should be made here first, committed to Git, pulled on the VPS, then deployed into the system Jitsi paths with the deploy script.

## Structure

```text
jitsi/
  config/
    politictalk.parallelglobe.io-config.js
  assets/
    public/politictalk/
      branding.json
      favicon.ico
      pgLogo.svg
      pg_bg.png
  interface_config/
    politictalk-overrides.js
  local/
    README.md
    custom-config.js
    custom-interface_config.js
    docker-compose.override.yml
  nginx/
    politictalk.parallelglobe.io.conf
  prosody-plugins/
    mod_politictalk_roles.lua
  scripts/
    deploy-vps.sh
    local-jitsi-setup.sh
    local-jitsi-start.sh
    local-jitsi-stop.sh
    local-jitsi-sync.sh
  templates/
  web/
    plugin.head.html
    title.html
```

## Current Meeting Policy

- Meetings start in audio-only mode.
- Participants join with microphone muted.
- Participants cannot unmute themselves until a host allows them through Jitsi AV moderation.
- Participants join with camera off.
- Jitsi prejoin is disabled because PgPlatform owns the PoliticTalk prejoin/auth step.
- Camera/premeeting camera controls are hidden.
- Toolbar is limited to microphone, chat, raise hand, fullscreen, noise suppression, participants pane, and hangup.
- Chat and polls are enabled.
- Invite/share controls are disabled.
- Room names are not stored in recent rooms.
- E2EE support is enabled in the Jitsi config.
- The logo and dynamic branding point to PoliticTalk public assets.
- Browser title, favicon, Open Graph metadata, and in-meeting watermark/logo use PoliticTalk branding.
- When JWT auth is enabled, Jitsi auto-owner is disabled so the first entrant cannot become moderator automatically.
- A custom Prosody module maps PoliticTalk JWT roles to Jitsi moderator/member roles, enables host-controlled AV moderation, and closes the room when the host leaves.

## Local Docker Testing

Local Jitsi testing uses the official Docker Jitsi release. The downloaded Docker files and generated runtime config are ignored by Git, while PoliticTalk overrides stay tracked in this repo.

First install and start Docker Desktop. Then:

```bash
cd /Users/amardeep/work/pg/jitsi
./scripts/local-jitsi-setup.sh
./scripts/local-jitsi-start.sh
```

Open:

```text
https://localhost:8443/pt-local-test
```

The local browser may show a self-signed certificate warning. That is expected.

When editing local override files or assets:

```bash
./scripts/local-jitsi-sync.sh
./scripts/local-jitsi-restart-web.sh
```

To stop local Jitsi:

```bash
./scripts/local-jitsi-stop.sh
```

## VPS Paths

The deploy script copies local files into these VPS paths:

```text
jitsi/config/politictalk.parallelglobe.io-config.js
  -> /etc/jitsi/meet/politictalk.parallelglobe.io-config.js

jitsi/assets/public/politictalk/*
  -> /etc/jitsi/meet/public/politictalk/
  -> /usr/share/jitsi-meet/images/politictalk/

jitsi/web/title.html
  -> /usr/share/jitsi-meet/title.html

jitsi/web/plugin.head.html
  -> /usr/share/jitsi-meet/plugin.head.html

jitsi/interface_config/politictalk-overrides.js
  -> appended to /usr/share/jitsi-meet/interface_config.js

jitsi/prosody-plugins/mod_politictalk_roles.lua
  -> /usr/share/jitsi-meet/prosody-plugins/mod_politictalk_roles.lua

jitsi/nginx/politictalk.parallelglobe.io.conf
  -> /etc/nginx/sites-available/politictalk.parallelglobe.io.conf
```

By default, the deploy script does not replace nginx config unless `DEPLOY_NGINX=1` is set.

## Deploy On VPS

After pulling the latest repo changes on the VPS:

```bash
cd /path/to/pg/jitsi
sudo ./scripts/deploy-vps.sh
```

To also deploy the nginx vhost:

```bash
cd /path/to/pg/jitsi
sudo DEPLOY_NGINX=1 ./scripts/deploy-vps.sh
```

For current `config.js`, branding, and asset changes, an nginx reload is enough. JWT/auth and Prosody plugin changes require restarting Prosody and Jicofo, and usually Jitsi Videobridge.

The `politictalk_roles` Prosody module should be configured with the PgApi
inactive-room and occupancy callbacks from
`templates/prosody-token-auth.cfg.lua.example`. The inactive callback clears the
event `meetingCode` when the last host leaves, and the occupancy callback keeps
the platform room cards updated with the current room occupancy count, including
the host. If the occupancy callback URL is omitted, the module derives it from
the inactive callback URL by replacing `room-inactive` with `room-occupancy`.

## Token Auth Rollout

The authenticated flow is:

```text
PgPlatform -> PgApi verifies event/user -> PgApi creates short-lived Jitsi JWT
-> PgPlatform prejoin/iframe -> Jitsi validates JWT on VPS
```

PgApi now supports JWT-backed `join-link` responses when these environment values are set:

```text
jitsi/templates/pgapi-politictalk-jwt.env.example
```

The VPS-side Prosody token-auth shape is documented here:

```text
jitsi/templates/prosody-token-auth.cfg.lua.example
```

Do not commit real secrets here. JWT secrets, Prosody passwords, and private keys should stay in VPS-only environment/config files.