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
🛠 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.	Google

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

👤 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.

BigBlueButton is a dozen coupled services. A package upgrade replaces their program files on disk but leaves the old processes running against files that no longer exist. The result is a server that looks completely healthy —- every service shows as active, the website loads, users can sign in —- while every attempt to start a meeting fails with an internal server error.

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.

🛠 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.