BBBEasy

BBBEasy is an open-source multipurpose meeting rooms manager for BigBlueButton.

Features

• Smooth installation experience.

• User friendly UI.

• Manage different configuration presets and assign them to rooms.

• Rooms management.

• Users management.

Components

The web-application is split in two parts:

• A server API.

• A modern front-end.

🪴 Project Activity

Development

The supported way to run BBBEasy locally is Docker Compose. It builds the frontend, the backend and nginx from this repository, so no image has to be pulled from a registry.

cp bbbeasy-backend/app/config/config-development.sample.ini bbbeasy-backend/app/config/config-development.ini
cp docker/config-production.sample.ini docker/config-production.ini
docker compose up -d
docker compose exec bbbeasy php vendor/bin/phinx migrate -e production

The second copy is the file the stack mounts into the backend container. It is ignored by git, so the BigBlueButton secret and anything else a deployment needs stay out of the repository. Copy it before the first docker compose up: Docker creates a directory in its place when the path does not exist, and the container then fails to read its configuration.

Service	Address
Web application	http://localhost:8080
API	http://localhost:8080/api
Outgoing mail	http://localhost:8025
PostgreSQL	localhost:55432

Set your BigBlueButton server and shared secret in your docker/config-production.ini before starting a room. The sources are baked into the images, so rebuild after a change:

docker compose build bbbeasy webserver && docker compose up -d

Outgoing mail

The Compose stack catches mail in mailpit, so nothing is sent outside. Point a deployment at a real server with these variables — anything left unset keeps the value in bbbeasy-backend/app/config/smtp.ini:

Variable	Sets
BBBEASY_SMTP_HOST	Server host name
BBBEASY_SMTP_PORT	Server port
BBBEASY_SMTP_SCHEME	ssl, tls, or empty for none
BBBEASY_SMTP_USERNAME	Account BBBEasy signs in with
BBBEASY_SMTP_PASSWORD	Password for that account
BBBEASY_SMTP_FROM_EMAIL	Address the mail comes from
BBBEASY_SMTP_SENDER_NAME	Name shown beside that address

A relay such as Postal signs in as one identity and sends as another, so the account, the address and the name are three separate settings:

BBBEASY_SMTP_HOST=postal.example.org
BBBEASY_SMTP_PORT=587
BBBEASY_SMTP_USERNAME=rooms-app-7f3c
BBBEASY_SMTP_PASSWORD=…
BBBEASY_SMTP_FROM_EMAIL=notifications@rooms.example.org
BBBEASY_SMTP_SENDER_NAME=Example Rooms

They are read from the environment so that a password can come from the deployment's own secret store rather than a file on the host.

Vagrant

The Vagrant box is still in the tree for the legacy workflow:

• To launch the backend in the development mode, follow these steps :

         1- Start a Command Prompt as an Administrator.

         2- Run cd /path/to/cloned/project/.

         3- Run vagrant up && vagrant ssh and wait until the end of the process.

         4- Run cp /app/bbbeasy-backend/app/config/config-development.sample.ini /app/bbbeasy-backend/app/config/config-development.ini.

• To launch the frontend in the development mode, follow these steps :

         1- Run cd /app/bbbeasy-frontend.

         2- (Optional) Run sudo /app/tools/bbbeasy --selfinstall to make bbbeasy available globally.

         3- On machines where the hostname is not bbbeasy.test, pass --env development to bbbeasy commands (e.g., ../tools/bbbeasy --env development --enableweb).

         4- Run yarn start-dev-installer to enable the installer app or yarn start-dev to enable the web app.

         The Vite dev server runs on port 3300 and the browser will open http://bbbeasy.test/ (via nginx).

Contributing

Security

Testing

BBBEasy follows a pyramid testing strategy — unit tests form the foundation, with E2E tests covering critical user journeys.

Backend — Unit Tests

The backend uses Atoum as its test framework. Tests cover all API endpoints, models, authentication, and permissions.

Command	Description
php vendor/bin/atoum -d tests/src	Run all backend tests
php vendor/bin/atoum -d tests/src/Actions/Account	Run account-related tests
php vendor/bin/atoum -d tests/src/Actions/Rooms	Run room-related tests
php vendor/bin/atoum -d tests/src/Models	Run model tests

Alternatively, from the browser:

• http://bbbeasy.test/api?statera — View test results
• http://bbbeasy.test/api?statera=withCoverage — View results with coverage report

Frontend — E2E Tests

End-to-end tests use Playwright and are organized into two independent suites:

Suite	File	Command
Installer	tests/e2e/installer.spec.ts	yarn test:e2e:installer
Web App	tests/e2e/webapp.spec.ts	yarn test:e2e:webapp
All	—	yarn test:e2e

Prerequisites

1. Enable the installer app as described in the Development section; installer.spec.ts only passes against a build made with VITE_INSTALLER_FEATURE=true.
2. Install the Chromium browser: npx playwright install chromium
3. Ensure the backend server is running and accessible.

The suite reads its target from the environment, so it can run against the Compose stack:

PGPORT=55432 VITE_APP_URL=http://localhost:8080 yarn test:e2e:webapp

PGHOST, PGPORT, PGUSER, PGPASSWORD and PGDATABASE select the database the tests read from, and VITE_APP_URL the deployment they drive.

Running Tests

# Run all E2E tests (installer + webapp)
yarn test:e2e

# Run only installer tests
yarn test:e2e:installer

# Run only webapp tests
yarn test:e2e:webapp

# Open interactive Playwright UI for debugging
yarn test:e2e:ui

# Run a specific test by name
npx playwright test -g "Test login"

Test Coverage

Module	Installer	Web App
Installation wizard (3 steps)	✅	—
Login / Register	—	✅
Password reset / change	—	✅
Roles (CRUD + permissions)	—	✅
Users (CRUD + status)	—	✅
Rooms (create)	—	✅
Presets (create)	—	✅
Labels (add)	—	✅
Recordings (view)	—	✅
Branding (view)	—	✅
Home / Landing / 404	—	✅

Technologies

Node.js

React JS

Redis

Percona Distribution for PostgreSQL

TypeSCript

Playwright

NGINX

Vagrant