# LoungeMesh Docker Setup for Spatial Video Events

> LoungeMesh turns a Jitsi deployment into a browser-based 2D video lounge with proximity audio, shared collaboration tools, and event controls. Its Docker workflow is practical for self-hosting, but the stack is broad and requires careful attention to media networking and embedded frontend configuration.

**fossasia/loungemesh** — Spatial video lounge for informal, hallway-style interactions.

- Repository: https://github.com/fossasia/loungemesh
- Website: https://www.loungemesh.com/
- Stars: 1,480 · Forks: 8
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/fossasia-loungemesh

## Why LoungeMesh Adds a Spatial Layer to Jitsi

LoungeMesh addresses a specific gap in conventional video meetings: placing participants in a shared, informal space instead of reducing every attendee to a tile or fixed call layout. Users move an avatar around a 2D room, and proximity affects real-time audio. The target users are organizers running online or hybrid events, particularly teams integrating with Eventyay or operating their own Jitsi services.

The project goes beyond video placement. Its documented feature set includes a synchronized infinite whiteboard, shared Markdown session notes, anonymous live polls, stage presentation mode, and room permissions. These features make it an event application rather than a spatial skin for Jitsi. Hosts can claim rooms, promote moderators, require a join PIN, admit participants through a lobby, and grant specific permissions. Event organizers can also schedule recurring rooms and synchronize them to Google Calendar through encrypted OAuth.

This breadth is both the main reason to consider LoungeMesh and its main adoption cost. An operator is not installing one web application. The stack includes the Vue SPA, an Express API, PostgreSQL, Redis, Jitsi Videobridge, Prosody, Jicofo, Jitsi web resources, Nginx, and Docker networking. The repository description positions the product around hallway-style interaction, but the documented architecture is a distributed conferencing and collaboration system.

## How Spatial Audio and Media Data Move

The frontend is a Vue 3 and TypeScript SPA built with Vite and Pinia. According to the repository layout and README, LoungeMesh uses `lib-jitsi-meet` as a headless WebRTC media engine rather than depending on the Jitsi iframe API. Jitsi Videobridge handles media while Prosody XMPP and Jicofo coordinate the conferencing control layer. The Express backend provides room state, collaboration data, roles, polls, notes, and related application behavior.

LoungeMesh computes real-time audio attenuation off the main browser thread through the Web Audio API and Web Workers. That design separates the frequently changing spatial calculation from other UI work, although the README does not publish latency figures or a detailed synchronization algorithm. Audio changes with avatar proximity, while visible video tiles occupy the shared 2D room.

The client does not stream every camera all the time. The README states that spatial viewport culling limits video to visible or on-stage peers and consumes no video bandwidth for off-screen peers. Documented resolution targets are 360p for avatar cameras and 720p at 15 to 30 fps for screenshares. On initial room entry, the client uses `/api/meetings/state/:roomName/init` to retrieve room state, role verification, notes, polls, whiteboard data, and background information in one request.

This is an application-specific protocol layered over a general media stack. A deployment must therefore keep the LoungeMesh API, Jitsi domain, XMPP configuration, browser client, and reverse proxy consistent. A working Jitsi server alone does not supply LoungeMesh's whiteboard, notes, polls, permissions, or spatial controls.

## Running the Full Docker Compose Stack

The documented local smoke path starts from the repository root. The first command installs dependencies and initializes the environment through `loungemesh.sh dev`. The second builds and starts the container stack. The README recommends Docker Compose for this path because it includes LoungeMesh, the backend API, PostgreSQL, Redis, and Jitsi media containers.

```bash
npm run setup
npm run docker:up
```

`npm run setup` delegates to `bash scripts/loungemesh.sh dev`, while `npm run docker:up` maps directly to `docker compose up -d --build`. After the containers start, the README lists LoungeMesh at `http://127.0.0.1:8780` and Jitsi Meet at `http://127.0.0.1:8001`.

Use `127.0.0.1` for the initial smoke check. The README warns that some systems resolve `localhost` to IPv6 first, which can reset mapped container ports. Opening the LoungeMesh URL is the first useful verification that the SPA, API, and Jitsi resources can reach one another. Opening the Jitsi URL separately checks the bundled Jitsi web stack. The README does not document a command-line room creation step for this first check, so no such step should be invented.

The Compose file binds LoungeMesh to loopback by default with `127.0.0.1:${LOUNGEMESH_PORT:-8780}:80` and `[::1]:${LOUNGEMESH_PORT:-8780}:80`. That is appropriate for local inspection, but remote access requires deliberate configuration rather than assuming the service is already exposed on a public interface.

## Local Development Without the Container Stack

Developers can instead run the Vue and Express processes on the host. This mode is useful for code changes and hot reloading, but the README does not claim that it starts PostgreSQL, Redis, Prosody, Jicofo, or Jitsi Videobridge. Those dependencies still need to exist if the selected features require them.

```bash
npm install
npm --prefix server install
npm run setup
```

The two install commands cover the root frontend and backend package trees. `npm run setup` creates the environment file and detects the LAN address according to the README.

```bash
npm --prefix server run prisma:migrate -- --name init
```

This applies the initial Prisma migration to the configured database. The generated environment values must point at reachable services; the README excerpt does not document every required value or the behavior when PostgreSQL is absent.

```bash
npm run dev
npm --prefix server run dev
```

The first command starts Vite on port 5173. The second starts the Express API on port 5000. These processes need to run separately. Unlike the Docker path, this sequence does not start the complete Jitsi stack, so an existing media deployment or additional service setup is necessary for a complete spatial call.

## Frontend Build Variables and Eventyay Boundaries

LoungeMesh embeds several `VITE_*` values during the production image build. The Dockerfile declares build arguments for `VITE_JITSI_PUBLIC_URL`, `VITE_XMPP_DOMAIN`, `VITE_XMPP_MUC_DOMAIN`, `VITE_SERVICE_URL`, `VITE_USE_WEBSOCKET`, `VITE_DISABLE_STUN_TURN_DISCOVERY`, Eventyay settings, `VITE_SESSION_PREFIX`, and `VITE_ALLOW_IFRAME_FROM`. These values become part of the SPA bundle through Vite's compile-time environment handling.

That distinction has an operational consequence. Changing one of these values after the image is built generally requires rebuilding the frontend image rather than merely restarting a container. The Compose configuration passes several arguments during `docker compose up -d --build`, so a rebuild is already part of the documented startup command.

The Jitsi client library is not copied into the SPA as a static asset. According to `docker-compose.yml`, LoungeMesh joins the `meet.jitsi` network and proxies `/libs/` to the `jitsi-web` container. This preserves Jitsi's serving model and makes the relationship between the two services visible at deployment time.

Nginx handles the static SPA and uses `NGINX_ALLOW_IFRAME_FROM` to populate the runtime CSP `frame-ancestors` directive. Cross-origin framing defaults to denial. Eventyay origins appear among the Compose defaults, but production operators should review the actual environment and header behavior rather than assuming the development defaults match their domain.

## LoungeMesh Compared with Standard Jitsi Meetings

The clearest alternative is a standard Jitsi deployment using the regular Jitsi Meet web interface. Both can use Jitsi media infrastructure, but LoungeMesh explicitly uses headless `lib-jitsi-meet` and adds its own Vue application, backend, spatial viewport, proximity attenuation, whiteboard, notes, polls, and access-control model. A regular Jitsi room follows that project's meeting interface and participant layout instead.

This difference affects integration work. An existing Jitsi deployment can serve as the media foundation for LoungeMesh, but LoungeMesh still requires its API and frontend configuration to agree on the XMPP and media services. By contrast, an organization that only needs conventional rooms, familiar participant tiles, and Jitsi's existing interface has little reason to add LoungeMesh's application layer.

LoungeMesh may still be preferable when proximity-based audio and shared event artifacts are part of the event design. Its single initialization endpoint, off-screen video culling, role-aware state, and stage mode are product decisions aimed at interactive events. They also make the state model more involved. The README does not provide a migration guide for existing Jitsi room data or an explicit compatibility matrix for standalone Jitsi versions.

## Limits, Maintenance Signals, and Upgrade Work

The largest limitation is infrastructure exposure. Self-hosting means operating PostgreSQL, Redis, the backend, Nginx, and multiple Jitsi components. Networked media also requires attention to public addressing, WebSocket configuration, and potentially STUN or TURN. `npm run fix:jvb` is documented for re-advertising the public IP on a running Jitsi Videobridge instance, but the README excerpt does not explain every remote-network failure mode.

LoungeMesh is not suitable when users require only a conventional meeting interface, when embedding through the Jitsi iframe API is a firm requirement, or when an operator cannot maintain the associated services. It is also a weak fit for organizations that require documented compatibility with arbitrary Jitsi versions but cannot test that combination themselves.

The repository is not archived, and its last push was on 2026-10-12. That is a recent maintenance signal, but it does not establish release discipline. There are no GitHub releases, and the root package version is `0.7.0`. Upgrading therefore cannot be planned from published GitHub release notes alone. Review `package-lock.json`, the pinned container images, deployment documentation, and repository changes before moving an existing deployment.

The root `package.json` is marked `private`, so the package is not intended for ordinary npm publication. The project uses the Apache-2.0 license. That permits use and modification under the license's conditions, but integrators must preserve required notices and review the complete license text. The stated license should not be treated as a guarantee that every container image or external service carries the same licensing terms.

## LoungeMesh Quality Gates Before Customization

The repository places substantial demands on contributors who change user flows, APIs, or architecture. It requires updates to `README.md`, `server/README.md`, relevant `docs-site/` material, and matching files under `.agents/skills/`. This documentation coupling may raise the cost of small internal changes, but it also makes the intended behavior more visible to contributors.

```bash
npm test
npm run typecheck
npm --prefix server run build
```

The README says `npm test` enforces 100% statement, branch, function, and line coverage. `npm run typecheck` runs `vue-tsc --noEmit`, while the prefixed server build compiles the backend with `tsc`. All are contributor quality gates, not first-use smoke checks.

```bash
npm run build && npm run test:e2e
```

Playwright covers end-to-end integration after a production frontend build. Documentation has its own build, which runs TypeDoc and then VitePress.

```bash
npm run docs:build
```

These checks matter because LoungeMesh spans browser code, API contracts, media configuration, and collaboration state. A typecheck alone cannot confirm browser-to-Jitsi behavior, and a backend test cannot validate iframe CSP rules. Operators adopting an unmodified release still need deployment-specific validation, especially for public media routes and event-specific OAuth configuration.

## Conclusion

LoungeMesh suits event operators and developers who need spatial interaction plus Jitsi media and can operate PostgreSQL, Redis, XMPP, and a reverse proxy as one stack. It is a poor fit for an organization seeking a small turnkey conferencing product or an iFrame-based integration. Before adoption, verify that `VITE_JITSI_PUBLIC_URL` matches the reachable Jitsi deployment, confirm the environment values created by `npm run setup`, and test the documented LoungeMesh and Jitsi smoke URLs from the intended client network.

## FAQ

### How do I install LoungeMesh with Docker Compose?

The documented path is to run `npm run setup` and then `npm run docker:up` from the repository root. After startup, the README lists LoungeMesh at `http://127.0.0.1:8780` and Jitsi Meet at `http://127.0.0.1:8001`.

### Does LoungeMesh require Jitsi to provide spatial video and audio?

Yes. LoungeMesh uses `lib-jitsi-meet`, while Jitsi Videobridge, Prosody XMPP, and Jicofo form the documented media stack. LoungeMesh adds its own spatial behavior, API, and collaboration features on top.

### Can I run only the LoungeMesh frontend and backend locally?

The README documents local commands for the Vite frontend on port 5173 and Express API on port 5000. That mode does not itself start PostgreSQL, Redis, or the complete Jitsi stack, so those services must be configured separately when required.

### What license does LoungeMesh use?

The repository states that LoungeMesh uses Apache-2.0. Users should consult the complete `LICENSE` file and review terms for external services and images separately.

## Sources

- [fossasia/loungemesh on GitHub](https://github.com/fossasia/loungemesh)
- [Issues](https://github.com/fossasia/loungemesh/issues)
- [License: Apache-2.0](https://github.com/fossasia/loungemesh/blob/main/LICENSE)
- [Project website](https://www.loungemesh.com/)
- [README](https://github.com/fossasia/loungemesh/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fossasia-loungemesh