Migration runbook
Migrating BigBlueButton from another provider
The safe unit of migration is the service, not the server. Inventory every API consumer, room frontend, recording path and DNS dependency before the first file is copied.
Executive brief
What matters
- 01
Prefer a fresh supported installation and migrate data; do not clone hidden problems into production.
- 02
Recording migration, frontend data and BigBlueButton API consumers are separate workstreams.
- 03
Lower DNS TTL early, freeze changes, define success metrics and keep the source intact through verification.
01
Inventory the whole service
Record BigBlueButton, Greenlight, Scalelite and operating-system versions; hostnames and certificates; API URL/secret consumers; SSO and SMTP settings; firewall and TURN configuration; recordings by state; storage mounts; backups; monitoring; and scheduled automation. Capture current load and a representative health baseline.
02
Build a clean destination
Install the supported BigBlueButton version on a clean dedicated host meeting official requirements. Apply configuration through persistent override mechanisms, establish monitoring and test media from external networks. If the move is also a major-version upgrade, follow the project’s clean-install guidance rather than an in-place shortcut.
03
Move each data class deliberately
Migrate Greenlight/PostgreSQL using application-aware backup and restore. Transfer published and required raw recordings using the BigBlueButton procedures appropriate to your versions, then rebuild or resynchronise metadata where required. Verify sample playback, captions and visibility—not only file counts.
04
Cut over with a rollback condition
Lower TTL in advance, freeze room and configuration changes, take final backups and switch the API hostname or frontend configuration. Run create/join/end/record tests and monitor real sessions. Define the time or error threshold that triggers rollback, and do not destroy the source until retention and stakeholder sign-off are complete.
Evidence base
Sources and further reading
We prefer project documentation and first-party product guidance. Community links are included where they reveal recurring operational questions rather than establish product guarantees.
- BigBlueButton installation and upgrade guidance docs.bigbluebutton.org ↗ (opens in a new tab)
- BigBlueButton customisation and recording transfer docs.bigbluebutton.org ↗ (opens in a new tab)
- BigBlueButton command-line diagnostics docs.bigbluebutton.org ↗ (opens in a new tab)
- Community recording resynchronisation discussions groups.google.com ↗ (opens in a new tab)
Practical answers
Questions teams ask
Can I copy a BigBlueButton VM image to the new provider?+
A fresh supported installation is generally safer because networking, kernel, certificates and hidden state change between environments. Migrate configuration and data intentionally.
Will existing recording links keep working?+
Only if hostname, metadata and recording paths remain compatible or redirects are designed. Test real historical links before cutover.
Should the API secret change?+
Plan for secret rotation, but coordinate every consumer. A staged endpoint or controlled cutover reduces the risk of silently breaking LMS integrations.
Continue the research
Related guides and infrastructure
Upgrade, backup and disaster recovery for BigBlueButton
Build a BigBlueButton runbook for upgrades, configuration, recordings, Greenlight data, restore tests and service recovery.
Read next → Security & governanceBigBlueButton recordings and privacy
Understand BigBlueButton capture, processing, publication, access, retention and deletion before enabling classroom recordings.
Read next → InfrastructureBigBlueButton hosting built around real-time media
Self-managed BigBlueButton hosting for organisations worldwide, on dedicated-compute VPS and bare metal with transparent specifications and optional deployment.
Read next →