Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

📝 Document conferencing setup for self-hosted instances

Luke Vellaf85bea2a2a20
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 1b869f49e..adc7c31ce 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -60,7 +60,8 @@
"self-hosting/introduction",
"self-hosting/installation/docker",
"self-hosting/configuration",
- "self-hosting/single-sign-on"
+ "self-hosting/single-sign-on",
+ "self-hosting/conferencing"
]
},
{
diff --git a/apps/docs/integrations/google-meet.mdx b/apps/docs/integrations/google-meet.mdx
index b387d6419..da605a368 100644
--- a/apps/docs/integrations/google-meet.mdx
+++ b/apps/docs/integrations/google-meet.mdx
@@ -17,7 +17,7 @@ The meeting space belongs to the Google account you connected, so it follows tha
## Requirements
- A Google account. A personal Google account or a Google Workspace account both work. On Google Workspace, your administrator must allow Google Meet and let you connect third party apps.
-- The Google Meet integration must be enabled on the Rallly instance you use. On rallly.co it is available to all accounts; on a self-hosted instance the administrator turns it on.
+- The Google Meet integration must be enabled on the Rallly instance you use. On rallly.co it is available to all accounts; on a self-hosted instance the administrator turns it on; see [Video Conferencing](/self-hosting/conferencing).
- Google Meet works on every plan, on rallly.co and self-hosted alike; the link is created when the poll is finalized.
## Adding the app
diff --git a/apps/docs/integrations/microsoft-teams.mdx b/apps/docs/integrations/microsoft-teams.mdx
index abcb95671..b49f209ca 100644
--- a/apps/docs/integrations/microsoft-teams.mdx
+++ b/apps/docs/integrations/microsoft-teams.mdx
@@ -23,7 +23,7 @@ The meeting is created on the Microsoft account you connected, so it follows you
- A Microsoft work or school account with a Microsoft Teams license. Personal Microsoft accounts (Outlook.com, Hotmail, Live) are not supported: Microsoft does not let apps create Teams meetings for them, so Rallly asks Microsoft for a work or school account when you connect.
- You must have used Teams at least once with that account. An account whose Microsoft 365 plan does not include Teams cannot create meetings.
- Your organization must let you approve Rallly, or an administrator must approve it for the organization. See [Admin approval](#admin-approval).
-- The Microsoft Teams integration must be enabled on the Rallly instance you use. On a self-hosted instance the administrator turns it on.
+- The Microsoft Teams integration must be enabled on the Rallly instance you use. On a self-hosted instance the administrator turns it on; see [Video Conferencing](/self-hosting/conferencing).
## Adding the app
diff --git a/apps/docs/integrations/webex.mdx b/apps/docs/integrations/webex.mdx
index ec12fdd1e..555013ff1 100644
--- a/apps/docs/integrations/webex.mdx
+++ b/apps/docs/integrations/webex.mdx
@@ -22,7 +22,7 @@ The meeting is created on the Webex account you connected, so it follows that ac
- A Webex account that can host meetings.
- Your organization must allow Webex integrations. Integrations are allowed by default; an administrator can block them in Control Hub. See [Organization restrictions](#organization-restrictions).
-- The Webex integration must be enabled on the Rallly instance you use. On a self-hosted instance the administrator turns it on.
+- The Webex integration must be enabled on the Rallly instance you use. On a self-hosted instance the administrator turns it on; see [Video Conferencing](/self-hosting/conferencing).
## Adding the app
diff --git a/apps/docs/integrations/zoom.mdx b/apps/docs/integrations/zoom.mdx
index e9d99b25f..bd3670cd1 100644
--- a/apps/docs/integrations/zoom.mdx
+++ b/apps/docs/integrations/zoom.mdx
@@ -21,7 +21,7 @@ The meeting is created on the Zoom account you connected, so it follows that acc
## Requirements
- A Zoom account. A free Zoom plan is enough.
-- The Zoom integration must be enabled on the Rallly instance you use. On rallly.co it is available to all accounts; on a self-hosted instance the administrator turns it on.
+- The Zoom integration must be enabled on the Rallly instance you use. On rallly.co it is available to all accounts; on a self-hosted instance the administrator turns it on; see [Video Conferencing](/self-hosting/conferencing).
## Adding the app
@@ -134,7 +134,7 @@ You can also remove the app from the Zoom side:
2. Click **Manage**, then **Added Apps**.
3. Find **Rallly** and click **Remove**.
-Removing the app from Zoom revokes Rallly's access. Zoom tells Rallly, which deletes the connection and the tokens it stored, so the account no longer appears in your settings. On a self-hosted instance, this needs the administrator to set up Zoom's deauthorization notice, which Zoom only sends for apps published on the Marketplace. If the account still appears in your settings, disconnect it in Rallly as well.
+Removing the app from Zoom revokes Rallly's access. Zoom tells Rallly, which deletes the connection and the tokens it stored, so the account no longer appears in your settings. On a self-hosted instance, this needs the administrator to set up [Zoom's deauthorization notice](/self-hosting/conferencing#zoom), which Zoom only sends for apps published on the Marketplace. If the account still appears in your settings, disconnect it in Rallly as well.
## Troubleshooting
diff --git a/apps/docs/self-hosting/conferencing.mdx b/apps/docs/self-hosting/conferencing.mdx
new file mode 100644
index 000000000..ce3629f87
--- /dev/null
+++ b/apps/docs/self-hosting/conferencing.mdx
@@ -0,0 +1,197 @@
+---
+icon: video
+title: Video Conferencing
+description: Let organizers add Google Meet, Zoom, Microsoft Teams and Webex links to their polls.
+---
+
+<Note>Available from v4.16.0 and later.</Note>
+
+With conferencing enabled, organizers connect a Google Meet, Zoom, Microsoft Teams or Webex account in **Settings** > **Conferencing**. When they finalize a poll, Rallly creates the meeting on that account and puts the join link in the event, the calendar invite and the confirmation emails. See the [integration guides](/integrations/google-meet) for what organizers see.
+
+Each provider needs an OAuth app that you register with the provider yourself. Rallly cannot ship one for you, because the redirect URI of an OAuth app is tied to your instance's domain. You can enable any combination of providers; on a self-hosted instance every provider is available on every plan.
+
+## Enable conferencing
+
+<Steps>
+ <Step title="Register an OAuth app">
+ Follow the setup for each provider you want below. Google Meet and Microsoft Teams reuse the app you may already have for [Single Sign-On](/self-hosting/single-sign-on).
+ </Step>
+ <Step title="Set the variables">
+ Add `CONFERENCING_ENABLED=true` and the provider's variables to your `.env`.
+ </Step>
+ <Step title="Restart">
+ Run `./rallly.sh restart`. **Conferencing** appears in **Settings** for every user who has at least one provider available.
+ </Step>
+</Steps>
+
+<ParamField path="CONFERENCING_ENABLED" default="false">
+ Turns on the Conferencing settings page and the **Add video call** options on the poll form. A provider is offered once its OAuth app variables are set. If this is `true` and no provider is configured, Rallly refuses to start.
+</ParamField>
+
+Every redirect URI below starts with your instance's public address, written as `https://<YOUR_DOMAIN>`. It must match exactly, including the scheme and without a trailing slash.
+
+## Google Meet
+
+Google Meet uses the same Google OAuth app as Google sign in and Google Calendar. If `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are already set, Google Meet is offered as soon as you set `CONFERENCING_ENABLED=true`, so finish the steps below first.
+
+<Accordion title="Setup">
+1. In the [Google Cloud console](https://console.cloud.google.com/), open the project that holds your OAuth client, or create one.
+
+2. Under **APIs & Services** > **Library**, enable the **Google Meet REST API**.
+
+3. Under **Google Auth Platform** > **Data Access**, add the scope `https://www.googleapis.com/auth/meetings.space.created`. Rallly also asks for `userinfo.email` and `userinfo.profile`.
+
+4. Under **Google Auth Platform** > **Audience**, choose who can connect:
+ - **Internal** if everyone using your instance is in your Google Workspace organization. Google does not review internal apps and shows no warning.
+ - **External** otherwise. `meetings.space.created` is a sensitive scope, so until Google verifies your app, users see an "unverified app" warning and the app is limited to 100 users. While the app is in **Testing**, only the test users you list can connect.
+
+5. Under **Google Auth Platform** > **Clients**, open your Web application client (or create one) and add this to **Authorized redirect URIs**:
+
+```
+https://<YOUR_DOMAIN>/api/integrations/callback/google-meet
+```
+
+Keep the existing `/api/auth/callback/google` URI if you use Google sign in.
+</Accordion>
+
+<ParamField path="GOOGLE_CLIENT_ID">
+ The client ID of your Google OAuth app. Shared with Google sign in and Google Calendar.
+</ParamField>
+
+<ParamField path="GOOGLE_CLIENT_SECRET">
+ The client secret of your Google OAuth app.
+</ParamField>
+
+## Zoom
+
+<Accordion title="Setup">
+1. Sign in to the [Zoom App Marketplace](https://marketplace.zoom.us/) and choose **Develop** > **Build App**. Create a **General App** that is **User managed**.
+
+2. Under **Basic Information**, set the **OAuth Redirect URL** and add the same address to the **OAuth Allow List**:
+
+```
+https://<YOUR_DOMAIN>/api/integrations/callback/zoom
+```
+
+3. Under **Scopes**, add `meeting:write:meeting` and `user:read:user`.
+
+4. Copy the **Client ID** and **Client Secret** from **Basic Information**.
+
+Until the app is published on the Marketplace, Zoom only lets users of the Zoom account that created it authorize it. If organizers use other Zoom accounts, submit the app for publication or add them as users of that account.
+</Accordion>
+
+<Accordion title="Deauthorization notices (optional)">
+When someone removes the app from their Zoom account, Zoom can tell Rallly so the connection disappears from their settings. Zoom only sends this notice for apps published on the Marketplace.
+
+1. Under **Features** > **Access**, turn on **Event Subscription** and add the endpoint:
+
+```
+https://<YOUR_DOMAIN>/api/integrations/zoom/deauthorize
+```
+
+2. Subscribe to the **App Deauthorized** event.
+
+3. Copy the **Secret Token** into `ZOOM_WEBHOOK_SECRET_TOKEN` and restart before Zoom validates the endpoint.
+</Accordion>
+
+<ParamField path="ZOOM_CLIENT_ID">
+ The client ID of your Zoom app. Set together with `ZOOM_CLIENT_SECRET`, or Rallly refuses to start.
+</ParamField>
+
+<ParamField path="ZOOM_CLIENT_SECRET">
+ The client secret of your Zoom app.
+</ParamField>
+
+<ParamField path="ZOOM_WEBHOOK_SECRET_TOKEN">
+ The secret token of the app's event subscription. Only needed for deauthorization notices.
+</ParamField>
+
+## Microsoft Teams
+
+Microsoft Teams uses the same Microsoft Entra ID registration as Microsoft sign in, with an extra redirect URI and Graph permissions. If `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` are already set, Teams is offered as soon as you set `CONFERENCING_ENABLED=true`, so finish the steps below first.
+
+<Accordion title="Setup">
+1. Register an application in the [Microsoft Entra admin center](https://entra.microsoft.com/), or open your existing one. See [Single Sign-On](/self-hosting/single-sign-on#microsoft) for sign in.
+
+2. Under **Authentication**, add a **Web** redirect URI:
+
+```
+https://<YOUR_DOMAIN>/api/integrations/callback/microsoft-teams
+```
+
+3. Under **API permissions**, add the delegated Microsoft Graph permissions `OnlineMeetings.ReadWrite`, `User.Read` and `offline_access`. If your organization does not let users consent to apps, choose **Grant admin consent**.
+
+Teams meetings can only be created for work or school accounts with a Teams license. With `MICROSOFT_TENANT_ID` set to `common` or `consumers`, Teams connects through the `organizations` endpoint; with a tenant ID it connects through that tenant.
+
+Administrators of other organizations can approve the app for their whole organization by opening `https://<YOUR_DOMAIN>/api/integrations/admin-consent/microsoft-teams`. See [Admin approval](/integrations/microsoft-teams#admin-approval).
+</Accordion>
+
+<ParamField path="MICROSOFT_CLIENT_ID">
+ The client ID of your Microsoft registration. Shared with Microsoft sign in.
+</ParamField>
+
+<ParamField path="MICROSOFT_CLIENT_SECRET">
+ The client secret of your Microsoft registration.
+</ParamField>
+
+<ParamField path="MICROSOFT_TENANT_ID" default="common">
+ The tenant of your Microsoft registration.
+</ParamField>
+
+## Webex
+
+<Accordion title="Setup">
+1. Sign in to the [Webex Developer Portal](https://developer.webex.com/) and choose **My Webex Apps** > **Create a New App** > **Integration**.
+
+2. Set the **Redirect URI**:
+
+```
+https://<YOUR_DOMAIN>/api/integrations/callback/webex
+```
+
+3. Select the scopes `meeting:schedules_write` and `spark:people_read`.
+
+4. Save, then copy the **Client ID** and **Client Secret**. Webex shows the secret only once.
+</Accordion>
+
+<ParamField path="WEBEX_CLIENT_ID">
+ The client ID of your Webex integration. Set together with `WEBEX_CLIENT_SECRET`, or Rallly refuses to start.
+</ParamField>
+
+<ParamField path="WEBEX_CLIENT_SECRET">
+ The client secret of your Webex integration.
+</ParamField>
+
+## Limiting a provider to some users
+
+While an OAuth app is waiting for review, or to try a provider before opening it to everyone, you can offer it to listed accounts only. Each variable takes a comma separated list of email addresses, matched exactly and case insensitively.
+
+Leaving a variable unset offers the provider to everyone. Setting it to an empty value offers it to nobody.
+
+<ParamField path="GOOGLE_MEET_ALLOWED_EMAILS">
+ Accounts that are offered Google Meet.
+</ParamField>
+
+<ParamField path="ZOOM_ALLOWED_EMAILS">
+ Accounts that are offered Zoom.
+</ParamField>
+
+<ParamField path="MICROSOFT_TEAMS_ALLOWED_EMAILS">
+ Accounts that are offered Microsoft Teams. Approving the app for an organization through the admin consent link is not limited.
+</ParamField>
+
+<ParamField path="WEBEX_ALLOWED_EMAILS">
+ Accounts that are offered Webex.
+</ParamField>
+
+## Troubleshooting
+
+**Rallly does not start after enabling conferencing.** `CONFERENCING_ENABLED` is `true` but no provider is configured, or only one of `ZOOM_CLIENT_ID` and `ZOOM_CLIENT_SECRET` (or the Webex pair) is set. Run `./rallly.sh logs web` to see which.
+
+**Conferencing does not appear in Settings.** `CONFERENCING_ENABLED` is not `true`, no provider's variables are set, or an allowlist above excludes the signed in account. Restart after editing `.env`.
+
+**The provider says the redirect URI does not match** (`redirect_uri_mismatch` on Google). The URI registered with the provider differs from the one Rallly sends. Compare it character by character with the URI above, including `https`, your exact domain and the provider name at the end.
+
+**Google shows an "unverified app" warning.** Your consent screen is External and Google has not verified the `meetings.space.created` scope. Users can continue past the warning, or you can make the app Internal or submit it for verification.
+
+**Connecting works but finalizing fails.** The provider refused to create the meeting. For Google Meet, check that the Google Meet REST API is enabled. For Teams, the account needs a Teams license. Disconnecting and reconnecting the account in Conferencing settings refreshes its tokens.
diff --git a/apps/docs/self-hosting/configuration.mdx b/apps/docs/self-hosting/configuration.mdx
index b1303da26..b7abfdf32 100644
--- a/apps/docs/self-hosting/configuration.mdx
+++ b/apps/docs/self-hosting/configuration.mdx
@@ -100,6 +100,12 @@ An SMTP server is required to send magic-link sign-in emails and notifications.
See the [Single Sign-On guide](/self-hosting/single-sign-on) for setup instructions and the full list of variables.
+## Video Conferencing
+
+Google Meet, Zoom, Microsoft Teams and Webex links on polls are turned on with `CONFERENCING_ENABLED` and an OAuth app per provider. See the [Video Conferencing guide](/self-hosting/conferencing) for setup instructions and the full list of variables.
+
+<Note>Available from v4.16.0 and later.</Note>
+
## Branding
Customise the look of your instance. These settings can also be changed from the Control Panel, where a saved value takes precedence over the environment variable. See [White Labeling](/self-hosting/white-labeling) for details.
@@ -142,6 +148,16 @@ Customise the look of your instance. These settings can also be changed from the
Override the Rallly Docker image. Pin a major version (e.g. `lukevella/rallly:4`) to avoid pulling in breaking changes. See the [releases](https://github.com/lukevella/rallly/releases) for available versions.
</ParamField>
+<ParamField path="RATE_LIMIT_ENABLED" default="true">
+ Limits how often one visitor can perform actions such as creating guest polls and submitting responses. Counts are kept in memory and reset when the container restarts. Rallly reads the visitor's address from the `X-Real-IP` header, so if you run your own reverse proxy, make sure it sets that header. The bundled proxy does. Set to `false` to turn the limits off.
+</ParamField>
+
+<ParamField path="EMAIL_QUEUE_SCHEDULER_ENABLED" default="true">
+ Sends queued emails, such as the invites that go to participants when a poll is finalized, from a timer inside the app every minute. The first emails of each batch go out straight away; the timer sends the rest and retries failures. Leave this on unless you trigger delivery some other way.
+
+ <Note>Available from v4.16.0 and later.</Note>
+</ParamField>
+
### External reverse proxy
The stack bundles Traefik for TLS termination. To put Rallly behind your own reverse proxy (Nginx, Caddy, Cloudflare Tunnel, etc.), set `PROXY_MODE=external` — the bundled `traefik` container is skipped and the `web` container is published on a host port your proxy can route to. See [External reverse proxy](/self-hosting/installation/docker#external-reverse-proxy) in the installation guide for the full setup.
diff --git a/apps/docs/self-hosting/single-sign-on.mdx b/apps/docs/self-hosting/single-sign-on.mdx
index 2849de895..ff935cb2e 100644
--- a/apps/docs/self-hosting/single-sign-on.mdx
+++ b/apps/docs/self-hosting/single-sign-on.mdx
@@ -60,7 +60,7 @@ Once the claims are present, a Microsoft sign-in whose address Microsoft does no
</Accordion>
<Accordion title="Using the same registration for Microsoft Teams">
-With `CONFERENCING_ENABLED=true`, the Microsoft registration also powers the [Microsoft Teams integration](/integrations/microsoft-teams); there are no separate Teams variables. Add the redirect URI:
+With `CONFERENCING_ENABLED=true` (see [Video Conferencing](/self-hosting/conferencing)), the Microsoft registration also powers the [Microsoft Teams integration](/integrations/microsoft-teams); there are no separate Teams variables. Add the redirect URI:
```
https://<YOUR_DOMAIN>/api/integrations/callback/microsoft-teams