How to setup Roombelt Self-hosted for Microsoft Office 365

Getting evaluation license

To run Roombelt self-hosted you need an evaluation license that you can get from [e-mail].

Introduction

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 container (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 Azure

Roombelt Self-hosted runs entirely on your infrastructure. To communicate with Microsoft Office 365 API, you need to create an Azure project as described below:

1. Open https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade and click "New registration".

2. Type any name, choose "Accounts in this organizational directory only (Single tenant)" and click "Register".

3. Open the registered application overview page.

4. Copy “Application (client) ID” and set it as the OFFICE365_DELEGATED_CLIENT_ID environment variable of the Roombelt docker container.

5. Copy "Directory (tenant) ID" and set it as the OFFICE365_DELEGATED_TENANT_ID environment variable.

6. Go to “Certificates and secrets” and create new client secret. Set any expiration date. Copy the client secret value and set it as the OFFICE365_DELEGATED_CLIENT_SECRET environment variable.

7. Go to API permissions, and click “Add a permission”. Select “Microsoft Graph” and then “Delegated permissions”. Select:

   • openid

   • profile

   • email

   • offline_access

   • Calendars.ReadWrite.Shared

   • User.Read

8. Go to “Authentication” and click “Add a platform”. Choose “Web” and type Redirect URI in the format https://<ROOMBELT_URL>/office365/delegated/oauth_callback. Set OFFICE365_DELEGATED_REDIRECT_URL environment variable of the Roombelt docker container to the value set above.

Configuration

Roombelt docker image accepts the following environment variables:

• OFFICE365_DELEGATED_CLIENT_ID - the Application (client) ID of the Azure application created in Creating an application in Azure.

• OFFICE365_DELEGATED_TENANT_ID - the Directory (tenant) ID of the Azure application created in Creating an application in Azure.

• OFFICE365_DELEGATED_CLIENT_SECRET - the Client secret of the Azure application created in Creating an application in Azure.

• OFFICE365_DELEGATED_REDIRECT_URL - the Redirect URI of the Azure application created in Creating an application in Azure.

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

Adding delegates for meeting rooms

To manage meeting rooms in Roombelt you need to set your Office 365 account as a delegate to the resource calendars. To do that:

1. Open https://admin.exchange.microsoft.com/#/resources/:/ResourceDetails
2. Click on the meeting room you want to manage in Roombelt and on the side panel go to tab "Delegation".

3. Scroll down to the section "Read and manage (Full Access)" and add the Office365 account used to sign in to Roombelt as a delegate.

4. As the Office365 account used to sign in to Roombelt go to Outlook Calendar.

5. In Outlook Calendar click "Add calendar" and open tab "Add from directory".

6. Search for the meeting room you want to manage in Roombelt and add it to the list of displayed calendars.

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 [e-mail].