politictalk/DEVELOPER_HANDOFF.md

PoliticTalk Jitsi Developer Handoff

This folder is the source of truth for the white-labeled PoliticTalk Jitsi setup served from:

https://politictalk.parallelglobe.io

The PoliticTalk VPS still runs the real Jitsi services. Local changes are made in this repo, committed, pushed, pulled on the VPS, then copied into the live Jitsi install with the deploy script.

Main Files

config/politictalk.parallelglobe.io-config.js
  Jitsi meeting policy: toolbar, audio-only behavior, prejoin, E2EE, branding URLs.

web/plugin.head.html
  Injected CSS and JavaScript for most visible UI customizations.
  This controls branding, mobile toolbar fixes, direct-access messaging,
  participant tile styling, role colors, hidden Jitsi controls, and layout patches.

web/title.html
  Browser title, favicon, and page metadata template.

web/manifest.json
  Web manifest used by the deployed Jitsi web app.

assets/public/politictalk/
  Public images and branding JSON, including logos, favicon, and background assets.

interface_config/politictalk-overrides.js
  Overrides appended to Jitsi's interface_config.js.

prosody-plugins/mod_politictalk_roles.lua
  Server-side room policy: JWT role mapping, moderator/member handling,
  host lifecycle, AV moderation, room inactive callback, and occupancy callback.

nginx/politictalk.parallelglobe.io.conf
  Nginx vhost and public asset routes for the PoliticTalk domain.

scripts/deploy-vps.sh
  Copies tracked files into the live Jitsi system paths and creates backups.

Normal Change Flow

Work locally from the Jitsi folder:

cd /Users/amardeep/work/pg/jitsi
git status --short

Edit the relevant files. Most UI changes go in:

web/plugin.head.html

Before committing, run quick checks:

git diff --check
awk '/^<script>$/{inside=1; next} /^<\/script>$/{inside=0} inside{print}' web/plugin.head.html | node --check -

Then commit and push:

git add .
git commit -m "Update PoliticTalk Jitsi UI"
git push

Use a specific commit message for non-UI work, for example auth, Prosody, nginx, or config changes.

Deploy On VPS

The current VPS checkout is expected at:

/opt/politictalk-jitsi-config

SSH into the VPS, pull the latest code, and run the deploy script:

ssh ubuntu@politictalk
cd /opt/politictalk-jitsi-config
git status --short
git pull --ff-only
sudo ./scripts/deploy-vps.sh

If the nginx vhost changed, deploy nginx too:

sudo DEPLOY_NGINX=1 ./scripts/deploy-vps.sh

The deploy script creates a backup under:

/root/jitsi-backups/YYYYMMDD-HHMMSS

It also reloads nginx automatically.

Restart Rules

For most UI and asset changes, this is enough:

sudo ./scripts/deploy-vps.sh

Then hard-refresh the browser or open a new incognito window.

For nginx changes:

sudo DEPLOY_NGINX=1 ./scripts/deploy-vps.sh

For Prosody plugin, JWT auth, moderator/participant policy, host lifecycle, or room callback changes, restart the Jitsi services after deploy:

sudo systemctl restart prosody
sudo systemctl restart jicofo
sudo systemctl restart jitsi-videobridge2

Quick Verification

Check that public assets are served:

curl -I https://politictalk.parallelglobe.io/images/politictalk/pgLogo.svg
curl -I https://politictalk.parallelglobe.io/images/politictalk/politictalk_logo_text.svg

Check that the deployed config includes the expected PoliticTalk settings:

curl -s https://politictalk.parallelglobe.io/config.js \
  | grep -E "startAudioOnly|toolbarButtons|dynamicBrandingUrl|defaultLogoUrl|prejoinConfig"

Manual smoke test from PgPlatform:

1. Create or open a PoliticTalk room from the platform.
2. Join as host and confirm the host is moderator.
3. Join as participant and confirm the participant is not moderator.
4. Confirm participant starts muted and cannot unmute without host action.
5. Confirm chat, raise hand, polls, fullscreen, and noise suppression work.
6. Confirm direct room access without platform/JWT shows the Parallel Globe account message.
7. Confirm mobile toolbar, participant tiles, and branding render correctly.

Rollback

Every deploy prints the backup path. To roll back, copy the backed-up files from that folder back to their original system paths, then reload/restart the relevant services.

Common live paths:

/etc/jitsi/meet/politictalk.parallelglobe.io-config.js
/etc/jitsi/meet/public/politictalk/
/usr/share/jitsi-meet/images/politictalk/
/usr/share/jitsi-meet/plugin.head.html
/usr/share/jitsi-meet/title.html
/usr/share/jitsi-meet/manifest.json
/usr/share/jitsi-meet/interface_config.js
/usr/share/jitsi-meet/prosody-plugins/mod_politictalk_roles.lua
/etc/nginx/sites-available/politictalk.parallelglobe.io.conf

After rollback:

sudo systemctl reload nginx

If Prosody/JWT logic was rolled back:

sudo systemctl restart prosody
sudo systemctl restart jicofo
sudo systemctl restart jitsi-videobridge2

Important Notes

• Do not edit the live Jitsi files manually on the VPS except for an emergency. Those changes will be overwritten by the next deploy.
• Do not commit secrets, JWT secrets, Prosody passwords, or generated Docker .env files.
• Public visual assets should go in assets/public/politictalk/.
• Keep plugin.head.html changes scoped and well-commented. Jitsi is a React app with generated class names, so prefer stable selectors such as IDs, aria labels, known wrapper classes, and classes that our script adds.
• The platform and PgApi are responsible for room creation, user validation, invite links, and Jitsi JWT generation. The Jitsi VPS validates the token and enforces in-room behavior.