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.

Developer Handoff

For the day-to-day edit, deploy, verify, and rollback workflow, see DEVELOPER_HANDOFF.md.

Structure

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:

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

Open:

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:

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

To stop local Jitsi:

./scripts/local-jitsi-stop.sh

VPS Paths

The deploy script copies local files into these VPS paths:

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:

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

To also deploy the nginx vhost:

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:

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:

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

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

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.