BigBlueButton Administration (ICT Staff)
FOR ICT STAFF · bbb.tangaza.ac.ke · BigBlueButton 3.0 with Greenlight and Keycloak
How the online-class system is put together, who can sign in, and what to do when it breaks.
ℹ️ Lecturer-facing instructions are in Running Online Classes with BigBlueButton. This page is the administrator's side: sign-in policy, roles, and server operations.
IN THIS GUIDE
- 🧩 How the system fits together
- 🔐 Part 1 · Who can sign in
- 👤 Part 2 · Roles, room limits and users
- 🎨 Part 3 · Site settings and branding
- 🖥 Part 4 · Server operations
- ⚠️ Part 5 · The upgrade rule
- 🎓 Part 6 ·
Connecting BigBlueButton to theThe LMS integration - 🛠 Troubleshooting
- 💬 Escalation
🧩 How the system fits together
Four moving parts. Knowing which one is broken saves most of the diagnosis time.
| Part | What it is | Where |
|---|---|---|
| BigBlueButton | The meeting engine - audio, video, screen share, recording. | Installed on the server itself |
| Greenlight | The website staff and students see: rooms, recordings, settings. | Docker container |
| Keycloak | The sign-in broker. Passes staff to Google and enforces the domain rule. | Docker container, at /keycloak |
| Google Workspace | Where the account actually lives. Same account as email and the LMS. |
A user signing in travels left to right: Greenlight → Keycloak → Google, and back again. A failure at any point looks the same to the user, so always establish which stage failed before changing anything.
🔐 Part 1 · Who can sign in
Access is restricted to tangaza.ac.ke accounts by three independent controls. They are deliberately redundant — any one of them can be misconfigured without opening the door.
| # | Control | Where it is set |
|---|---|---|
| 1 | OAuth consent screen set to Internal | Google Cloud Console, in the project that owns the OAuth client |
| 2 | Hosted Domain = tangaza.ac.ke | Keycloak → realm greenlight → Identity providers → google |
| 3 | Allowed Domains = tangaza.ac.ke | Greenlight → Administrator Panel → Site Settings → Registration |
⚠️ Control 2 is the one that does the work. If Hosted Domain is ever cleared, any personal Gmail account can sign in and will look like a legitimate user. Check it after any Keycloak change.
1.1 Joining a class is separate from signing in
Requiring a Tangaza account to have an account is not the same as requiring one to join a meeting. That second control lives on each room: Require users to be signed in before joining. It is off by default. Standard practice for teaching rooms is on - the lecturer guide says so.
1.2 Break-glass access
The ordinary Sign in button goes to Keycloak. The original username-and-password form still exists at /signin. Keep exactly one local administrator account, with its password in the University password manager, for the day Keycloak or Google is unavailable. Do not use it for daily work.
👤 Part 2 · Roles, room limits and users
Everything here is under Administrator Panel (top-right menu → Administrator Panel).
| Task | Where |
|---|---|
| Promote someone to Administrator | Manage Users → the user → Role |
| Raise how many rooms a role may create | Roles → the role → Room Limit |
| Assign roles automatically by email suffix | Site Settings → Registration → Role Mapping |
| Stop self-registration of local accounts | Site Settings → Registration → Registration Method → Invite |
⚠️ Role Mapping applies only when an account is first created. Set it before a group of new staff sign in, not after — existing accounts keep whatever role they already have, and you will be promoting people by hand.
Roles cannot be read from Google or Keycloak. Email-suffix mapping is the only automatic mechanism available.
2.1 Lecturers who teach many units
One room per unit is the documented convention, so a lecturer with six units needs six rooms. If they report that + New Room does nothing, raise the Room Limit on their role rather than telling them to share one room.
🎨 Part 3 · Site settings and branding
Administrator Panel → Site Settings controls the whole site: the Tangaza crest, the primary colour, links to the University's acceptable-use policy and privacy policy, and the maintenance banner.
The maintenance banner is the fastest way to tell everyone something — use it before planned downtime and clear it afterwards.
Host the crest on this server rather than an external site, so branding does not break when something outside the University moves.
🖥 Part 4 · Server operations
Greenlight, Keycloak, PostgreSQL and Redis run as Docker containers from a single directory on the server. BigBlueButton itself runs as ordinary system services managed with bbb-conf.
| Task | Command |
|---|---|
| See what is running | docker compose ps in the Greenlight directory |
| Greenlight logs | docker compose logs --tail 100 greenlight-v3 |
| Restart Greenlight | docker compose up -d --force-recreate greenlight-v3 |
| Check BigBlueButton | bbb-conf --check |
| Restart BigBlueButton | bbb-conf --restart |
| Confirm the API is healthy | curl -s https://bbb.tangaza.ac.ke/bigbluebutton/api — expect SUCCESS |
ℹ️ After restarting Greenlight the site returns 502 Bad Gateway for 60 to 90 seconds while it rebuilds its assets. This is normal. Wait for Listening on in the logs before concluding anything is wrong.
4.1 Before you change anything
Take a database backup first. It covers Greenlight's rooms and recordings index and Keycloak's realm in one file, and it is the only thing that makes a bad change reversible.
⚠️ Part 5 · The upgrade rule
🚫 Never run apt upgrade on this server without immediately running bbb-conf --restart afterwards.
This has already happened once, on 14 August 2026. Diagnosis took far longer than the fix, which was a single restart.
Plan operating-system upgrades as maintenance windows, and reboot afterwards if the kernel, glibc, OpenSSL or Docker were among the packages upgraded.
🎓 Part 6 · Connecting BigBlueButton to theThe LMS integration
Lecturers can add a live class as an activity inside a Moodle unit, which givesgiving them open and close times, calendar entries and recordings kept with the course. ItThis onlyis worksalready onceconfigured and working. What follows is the LMScurrent isstate, pointedplus atwhat to do if it ever has to be rebuilt.
6.1 Current state
Checked 15 August 2026 on lms.tangaza.ac.ke:
https://bbb.tangaza.ac.ke/bigbluebutton/
✅ our 🚫
6.12 CheckKnown issue: the plugin is therethe old contributed one
⚠️ Every other activity module on the LMS reports version 2025041400, matching Moodle 5.0. BigBlueButton reports 2021101017 — release 3.0.9, published October 2021. Moodle core's own BigBlueButton module has been partdisplaced by the older Blindside Networks contributed plugin of the same name.
Why it matters: the plugin is around four and a half years older than the Moodle coreit sinceruns on. It misses upstream fixes, sits outside Moodle's testing for this release, and is a likely casualty of the next Moodle upgrade.
Why now is the moment: Moodleone 4.0activity exists across all courses., The blast radius will never be smaller than this. After a semester of lecturers using it, this becomes a much bigger job.
The fix, in outline — maintenance window, database and moodledata backup first:
mod/bigbluebuttonbn 6.3 Rebuilding the integration from the Moodle plugins directory first.
6.2 Point it at our serverscratch
Get the values from the BigBlueButton server:
bbb-conf --secret
Then in the LMS, go to Site administration → Plugins → Activity modules → BigBlueButton and set::
| Setting | Value |
|---|---|
| BigBlueButton |
https://bbb.tangaza.ac.ke/bigbluebutton/ — |
| BigBlueButton |
The Secret line from bbb-conf --secret |
Save,🚫 thenA createfresh aMoodle points this at Blindside Networks' public test activityserver. inSessions acreated sandbox course and start a session. Ifbefore it fails,is thechanged two usual causes are a missing trailing slashrun on thesomeone URLelse's and a secret copiedinfrastructure with a trailing60-minute space.cap. Check this setting after any Moodle rebuild or restore.
6.34 Which route should lecturers use
Both routes reach the same server, and a lecturer may use both.
| Route | Best for | Access control |
|---|---|---|
| LMS activity | Taught units with enrolled students | Course enrolment — strongest, nothing to forward |
| Greenlight room + Google Calendar | Staff meetings, interviews, supervision, guests | Sign-in requirement and access code |
The lecturer guide documents both and tells staff which to pick.
6.4 What this does not change
Sessions started from the LMS still run on this server and still consume its capacitycapacity. — theThe integration changes who schedules a meetingclass and how students reach it, not where it runs.
6.5 planningThe staysLMS itself
The LMS runs Moodle 5.0 (Build 20250414). Point releases to 5.0.9 have since been published carrying security fixes, and Moodle's notifications page also flags development directories (/vendor, /node_modules) present on the same.public site. Both are LMS-side jobs rather than BigBlueButton ones, but they affect the same service as far as a lecturer is concerned.
🛠 Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Site shows 502 Bad Gateway | Greenlight is still starting | Wait 90 seconds. If it persists, check the container logs. |
| Site loads, but no meeting will start | BigBlueButton API returning 500 — usually packages upgraded without a restart | bbb-conf --restart, then confirm the API returns SUCCESS. |
| Sign-in ends on "Invalid redirect uri" | The Keycloak client is missing a redirect or post-logout URI | Keycloak → Clients → greenlight → add the site address with a trailing /* to both fields. |
| A personal Gmail account signed in | Hosted Domain has been cleared | Reset it on the google identity provider, then audit recently created users. |
| A returning user has lost their rooms | Their sign-in was not matched to their existing account | Do not create them a new account — contact the Greenlight administrator, the accounts can be re-linked. |
| New staff land on the wrong role | Role Mapping was set after they first signed in | Fix the role by hand in Manage Users, and correct the mapping for the next intake. |
| Recordings never appear | Recording processing has stalled | Check disk space, then the recording services with bbb-conf --check. |
💬 Escalation
Before escalating, collect: what the user saw, their email address, the room name, the time, and whether curl -s https://bbb.tangaza.ac.ke/bigbluebutton/api returns SUCCESS. That last one separates "BigBlueButton is down" from everything else and is worth ten minutes of guessing.
Sign-in problems that affect every user at once are almost always Keycloak or the Google OAuth client, not Greenlight.