How to setup Roombelt Self-hosted for Google Calendar

Getting evaluation license

To run Roombelt self-hosted you need an evaluation license that you can get from


Roombelt Self-hosted is distributed as a docker image and is available on Docker Hub. This document does not cover provisioning and maintaining the docker application (including setting up an SSL certificate for HTTPS).

We recommend pinning to a specific Roombelt version instead of using the latest docker image tag. New Roombelt versions might require a database schema update to work.

Creating an application in Google Cloud Console

Roombelt Self-hosted runs entirely on your infrastructure. To communicate with Google Calendar API, you need to create a Google Cloud project as described below:

  1. Create a new project using the Create Project button.

  2. In the new project go to API Library and enable the following API-s

    1. Google Calendar API

    2. Google People API

  3. Go to OAuth consent screen, select “Internal” User Type, set Product name shown to users to value Roombelt, and set the developer contact email. Leave the other fields empty.

  4. Go to Credentials and click Create Credentials -> OAuth client ID

    1. Choose Application type to value Web application

    2. Set Authorized redirect URIs to https://<ROOMBELT_URL>/google/oauth_callback

  5. Click Save

  6. Store Client ID and Client secret somewhere - you will need them shortly.


Roombelt docker image accepts the following environment variables:

  • GOOGLE_CLIENT_ID - the Client ID that you saved in the previous steps.

  • GOOGLE_CLIENT_SECRET - the Client Secret that you saved in the previous steps.

  • GOOGLE_REDIRECT_URL - the Authorized redirect URIs that you’ve configured in the Google Cloud in the previous steps.

  • (Optionally) GOOGLE_WEB_HOOK_URL - set it to https://<ROOMBELT_URL>/google/web_hook. If this variable is set, Roombelt uses webhooks instead of short polling Google Calendar API. As this is yet another point of failure it’s recommended to not set the variable unless the installation is reaching Google API limits.

  • PORT defines a port the application will bind to (defaults to 3000).

  • LICENSE_KEY is the license key you can get from the Roombelt team.

  • DATABASE_URL - see Supported databases.

  • UPDATE_DATABASE_SCHEMA - see Creating the database schema.

  • (Optionally) SMTP_URI is used to send email notifications about offline devices (displays).

  • (Optionally) ALLOWED_EMAILS is the email address of the service account used to configure meeting room displays in your organization. This will block access to your Roombelt instance for other users from your organization and users from other organizations.

Supported databases

Roombelt supports PostgreSQL 12 or newer and SQLite databases.

To use SQLite, set DATABASE_URL to sqlite:/roombelt/db/roombelt.sqlite and mount /roombelt/db as a volume in docker so that the database survives application restarts.

For details on the database URL for PostgreSQL, visit this documentation page.

Creating the database schema

Roombelt creates and updates the database schema automatically if the UPDATE_DATABASE_SCHEMA variable is set to true in the configuration file. Interrupting the database update process can permanently break the database.

To create the Roombelt database schema:

  1. Start Roombelt with the environment variable UPDATE_DATABASE_SCHEMA set to true.

  2. Wait about a minute to ensure the database schema is created.

  3. Stop Roombelt, set UPDATE_DATABASE_SCHEMA=false, and restart the application.

Updating the database schema

New versions of Roombelt might require a database schema update. The process of updating the database is:

  1. Stop Roombelt docker container.

  2. Backup Roombelt database (for SQLite creating a copy of the folder with the database file is sufficient).

  3. Start a new version of Roombelt with UPDATE_DATABASE_SCHEMA=true.

  4. Wait about a minute to ensure the database schema is created.

  5. Stop Roombelt, set UPDATE_DATABASE_SCHEMA=false, and start the application.

Always create database backups before updating the database schema.

Keeping uploaded files

Uploaded device background files are kept in /roombelt/uploads inside the docker container. You need to mount a volume on this path so uploaded files persist during service restart.

Final notes

In case of any issues, reach out to

Last updated