Skip to content

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

πŸ“ Update rallly-selfhosted for batteries included setup (#2346)

Luke Vella03596abd9d49
diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index d21de0de6..a14433ff3 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -48,14 +48,13 @@
"group": "Get Started",
"pages": [
"self-hosting/introduction",
- {
- "group": "Installation",
- "icon": "server",
- "pages": ["self-hosting/installation/docker"]
- },
+ "self-hosting/installation/docker",
+ "self-hosting/configuration",
+ "self-hosting/single-sign-on",
+ "self-hosting/management",
+ "self-hosting/migration",
"self-hosting/licensing",
- "self-hosting/white-labeling",
- "self-hosting/configuration"
+ "self-hosting/white-labeling"
]
},
{
diff --git a/apps/docs/self-hosting/configuration.mdx b/apps/docs/self-hosting/configuration.mdx
index 8a42aa826..b6d2dc3d3 100644
--- a/apps/docs/self-hosting/configuration.mdx
+++ b/apps/docs/self-hosting/configuration.mdx
@@ -1,266 +1,183 @@
---
icon: gear
title: Configuration Options
-description: Using environment variable to configure a self-hosted instance of Rallly.
+description: Environment variables for a self-hosted Rallly instance.
---
+All configuration lives in the `.env` file at the root of your self-hosted stack. The [installer](/self-hosting/installation/docker) writes a starter `.env` for you; edit it directly to change any value. After edits, apply them with `./rallly.sh restart`.
+
+<Note>
+ Internal wiring (database URL, S3 endpoint, `NEXT_PUBLIC_BASE_URL`) is handled by the Compose stack and derived from the values below. You do not need to set them yourself.
+</Note>
+
## General
-<ParamField path="NEXT_PUBLIC_BASE_URL" required>
- The base url where this instance is accessible, including the scheme (eg.
- `http://` or `https://`), the domain name, and optionally a port.
+<ParamField path="DOMAIN" required>
+ The domain where your instance is served (e.g. `rallly.example.com`). Traefik uses this to request a Let's Encrypt certificate and to route traffic to the app.
+</ParamField>
+
+<ParamField path="ACME_EMAIL" required>
+ Email address for Let's Encrypt certificate notifications (expiry warnings, etc.).
</ParamField>
<ParamField path="SECRET_PASSWORD" required>
- A random 32-character secret key used to encrypt user sessions
+ A random secret key used to encrypt user sessions. Must be at least 32 characters. Generate one with `openssl rand -base64 32`.
</ParamField>
<ParamField path="SUPPORT_EMAIL" required>
- This email will be shown as the contact email for support queries.
+ Shown to users as the contact email for support queries.
</ParamField>
<ParamField path="NOREPLY_EMAIL">
- This email is used as the sender for all transactional emails. If not set,
- `SUPPORT_EMAIL` will be used instead.
+ Sender address for all transactional emails. Falls back to `SUPPORT_EMAIL` if not set.
</ParamField>
<ParamField path="NOREPLY_EMAIL_NAME" default="Rallly">
- This name is used as the sender name for all transactional emails.
+ Sender name for all transactional emails.
</ParamField>
<ParamField path="INITIAL_ADMIN_EMAIL">
- Specifies the email address of the first user who will be eligible to become an administrator. After the application starts, the user with this email address must navigate to `/control-panel` and click a button to claim their admin role.
-</ParamField>
-
-
-## Database
-
-<ParamField path="DATABASE_URL" required>
- Postgres database connection string
+ The first user who signs in with this email can claim the admin role from `/control-panel`. See the [Control Panel guide](/self-hosting/control-panel).
</ParamField>
## Email (SMTP)
-<ParamField path="SMTP_HOST">The host address of your SMTP server</ParamField>
+An SMTP server is required to send magic-link sign-in emails and notifications.
-<ParamField path="SMTP_PORT">
- The port of your SMTP server. Common values: 587 (STARTTLS), 465 (SSL), 25 (plain).
+<ParamField path="SMTP_HOST" required>The host address of your SMTP server</ParamField>
+
+<ParamField path="SMTP_PORT" default="587">
+ Common values: 587 (STARTTLS), 465 (implicit TLS), 25 (plain). Ports 587 and 25 use STARTTLS and require `SMTP_SECURE=false`; port 465 uses implicit TLS and requires `SMTP_SECURE=true`.
</ParamField>
<ParamField path="SMTP_SECURE" default="false">
- Set to "true" if SSL is enabled for your SMTP connection (typically for port 465)
+ Set to `true` for implicit TLS (typically port 465). Leave as `false` for STARTTLS (typically port 587), which upgrades a plain connection to TLS after the initial handshake.
</ParamField>
-<ParamField path="SMTP_USER" default="">
- The username (if auth is enabled on your SMTP server)
+<ParamField path="SMTP_USER">
+ SMTP username, if authentication is enabled.
</ParamField>
-<ParamField path="SMTP_PWD" default="">
- The password (if auth is enabled on your SMTP server)
+<ParamField path="SMTP_PWD">
+ SMTP password, if authentication is enabled.
</ParamField>
<ParamField path="SMTP_REJECT_UNAUTHORIZED" default="true">
- Validate TLS certificates. Set to `false` to ignore certificate errors (useful for self-signed certificates, not recommended for production)
-
- <Note>This option is only available from v4.4.0 and later.</Note>
+ Validate TLS certificates. Set to `false` to accept self-signed certificates. Not recommended for production.
+
+ <Note>Available from v4.4.0 and later.</Note>
</ParamField>
<ParamField path="SMTP_TLS_SERVERNAME">
- Sets the hostname used for TLS certificate validation. Required when `SMTP_HOST` is set to an IP address or a hostname that only exists in `/etc/hosts` (not resolvable via DNS), as nodemailer cannot determine the correct servername automatically in those cases. See [nodemailer TLS options](https://nodemailer.com/smtp#tls-options) for more details.
+ Hostname used for TLS certificate validation. Required when `SMTP_HOST` is an IP address or a hostname that only resolves via `/etc/hosts`. See [nodemailer TLS options](https://nodemailer.com/smtp#tls-options).
- <Note>This option is only available from v4.8.0 and later.</Note>
-</ParamField>
-
-<ParamField path="SMTP_TLS_ENABLED">
- <Warning>Deprecated: Use `SMTP_REJECT_UNAUTHORIZED=false` to disable certificate validation</Warning>
- Legacy option that is no longer used
+ <Note>Available from v4.8.0 and later.</Note>
</ParamField>
## Auth
<ParamField path="EMAIL_LOGIN_ENABLED" default="true">
- Set to "false" to disable email-based login (magic link authentication).
- When disabled, users can only authenticate via configured OAuth providers
- (Google, Microsoft, OIDC) and user registration is automatically disabled.
-
- <Note>This option is only available from v4.4.0 and later.</Note>
+ Set to `false` to disable magic-link email sign-in. When disabled, users can only sign in via a configured SSO provider, and registration is disabled.
+
+ <Note>Available from v4.4.0 and later.</Note>
</ParamField>
<ParamField path="REGISTRATION_ENABLED" default="true">
- Set to "false" to disable user registration globally. This environment variable
- takes precedence over the database setting configured via the admin UI.
- Registration requires email login to be enabled.
-
- <Note>This option is only available from v4.4.0 and later.</Note>
+ Set to `false` to disable new user registration. Takes precedence over the database setting in the admin UI.
+
+ <Note>Available from v4.4.0 and later.</Note>
</ParamField>
<ParamField path="ALLOWED_EMAILS">
- Comma separated list of email addresses that are allowed to register and
- login. Wildcard characters are supported. Example: Setting it to
- `*@example.com` to allow anyone with a `@example.com` email address.
+ Comma-separated list of email addresses allowed to register and sign in. Wildcards are supported. Example: `*@example.com` allows any address on that domain.
</ParamField>
-### Google
+### Single Sign-On
-<Accordion title="Setup">
-1. Head over to the Credentials tab: https://console.developers.google.com/apis/credentials
+See the [Single Sign-On guide](/self-hosting/single-sign-on) for setup instructions and the full list of variables.
-2. Create a OAuth client ID. This will be your `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
+## Branding
-3. Set "Authorized redirect URIs" to include your full domain and end in the callback path:
+Customise the look of your instance. See [White Labeling](/self-hosting/white-labeling) for details.
-```
-https://<YOUR_DOMAIN>/api/auth/callback/google
-```
-</Accordion>
+<Note>
+ Available from v4.6.0 and later. Requires an Enterprise license with the white-label add-on.
+</Note>
-<ParamField path="GOOGLE_CLIENT_ID">
- The client ID of your Google application
+<ParamField path="APP_NAME" default="Rallly">
+ Application name. Appears in page titles, navigation, and emails.
</ParamField>
-<ParamField path="GOOGLE_CLIENT_SECRET">
- The client secret of your Google application
+<ParamField path="PRIMARY_COLOR" default="#4f46e5">
+ Primary brand color for light mode. Must be a valid hex code.
</ParamField>
-### Microsoft
-
-<Accordion title="Setup">
-Follow the instructions here to create a Microsoft Entra ID application: https://docs.microsoft.com/en-us/entra/identity-platform/quickstart-register-app
-
-After creating the application, set the redirect URI to include your full domain and end in the callback path:
-
-```
-https://<YOUR_DOMAIN>/api/auth/callback/microsoft-entra-id
-```
-</Accordion>
-
-<ParamField path="MICROSOFT_TENANT_ID">
- The tenant ID of your Microsoft application
+<ParamField path="PRIMARY_COLOR_DARK">
+ Primary brand color for dark mode. Auto-calculated from `PRIMARY_COLOR` if not set.
</ParamField>
-<ParamField path="MICROSOFT_CLIENT_ID">
- The client ID of your Microsoft application
+<ParamField path="LOGO_URL" default="/static/logo.svg">
+ URL to your logo for light mode. SVG recommended.
</ParamField>
-<ParamField path="MICROSOFT_CLIENT_SECRET">
- The client secret of your Microsoft application
+<ParamField path="LOGO_URL_DARK">
+ URL to your logo for dark mode. Falls back to `LOGO_URL` if not set.
</ParamField>
-### Custom SSO (OIDC)
-
-The following must be set for OIDC to work:
-
-- `OIDC_DISCOVERY_URL`
-- `OIDC_CLIENT_ID`
-- `OIDC_CLIENT_SECRET`
-
-<Accordion title="Setup">
-Your OAuth 2.0 application needs to be configured with the following scopes:
-
-- `openid`: Essential for OIDC to function, used to perform authentication.
-- `profile`: Access to the user's personal information such as name and picture.
-- `email`: Access to the user's email address.
-
-Your identity provider should redirect the user back to the following URL:
-
-```
-https://<YOUR-DOMAIN>/api/auth/callback/oidc
-```
-</Accordion>
-
-<ParamField path="OIDC_NAME" default="OpenID Connect">
- The display name of your provider as it will be shown on the login page
+<ParamField path="LOGO_ICON_URL" default="/images/rallly-logo-mark.png">
+ URL to your logo icon, used in emails and as a favicon.
</ParamField>
-<ParamField path="OIDC_DISCOVERY_URL">
- URL of the `.well-known/openid-configuration` endpoint for your OIDC provider
+<ParamField path="HIDE_ATTRIBUTION" default="false">
+ Set to `true` to hide "Powered by Rallly" attribution in polls and emails.
</ParamField>
-<ParamField path="OIDC_ISSUER_URL">
- <Warning>Deprecated from v4.5.0: This option is no longer used.</Warning>
- URL of the issuer for your OIDC provider. You can get this from your OpenId
- Configuration endpoint.
-</ParamField>
+## Advanced
-<ParamField path="OIDC_CLIENT_ID">
- The client ID of your OIDC application
+<ParamField path="RALLLY_IMAGE" default="lukevella/rallly:4">
+ 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="OIDC_CLIENT_SECRET">
- The client secret of your OIDC application
-</ParamField>
+### External reverse proxy
-<ParamField path="OIDC_NAME_CLAIM_PATH" default="name">
- The path to the claim that contains the user's name
-</ParamField>
+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.
-<ParamField path="OIDC_EMAIL_CLAIM_PATH" default="email">
- The path to the claim that contains the user's email address
+<ParamField path="PROXY_MODE" default="bundled">
+ Set to `external` to disable the bundled Traefik reverse proxy and publish the `web` container on a host port instead. Your external proxy is responsible for TLS termination.
</ParamField>
-<ParamField path="OIDC_PICTURE_CLAIM_PATH" default="picture">
- The path to the claim that contains the user's profile picture
+<ParamField path="WEB_PORT" default="127.0.0.1:3000">
+ Host port binding for the `web` container when `PROXY_MODE=external`. Format is `<host>:<port>`. Use `0.0.0.0:3000` to expose on all interfaces, or pick a different port if 3000 is in use.
</ParamField>
-<Info>Use dot notation in `_CLAIM_PATH` fields to access nested objects.</Info>
-
-## Storage (S3)
+### External database
-Storage configuration is optional but required to enable features like user avatar uploads.
-For self-hosted deployments, [Garage](https://garagehq.deuxfleurs.fr/) is the recommended S3-compatible storage solution. Alternatively, you can use cloud services like [AWS S3](https://aws.amazon.com/s3/), [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces), or [Cloudflare R2](https://www.cloudflare.com/developer-platform/r2/).
+The stack bundles a PostgreSQL container that works out of the box. Set `DATABASE_URL` in `.env` to point at an external Postgres instead (RDS, Supabase, Neon, etc.) β€” the bundled `db` container is skipped automatically when this variable is set.
-<ParamField path="S3_BUCKET_NAME">
- The name of your S3 bucket
+<ParamField path="DATABASE_URL">
+ Postgres connection string. Leave unset to use the bundled database. Example: `postgres://user:[email protected]:5432/rallly`.
</ParamField>
-<ParamField path="S3_ACCESS_KEY_ID">
- The access key ID of your S3 server
-</ParamField>
+### External object storage
-<ParamField path="S3_SECRET_ACCESS_KEY">
- The secret access key of your S3 server
-</ParamField>
-
-<ParamField path="S3_REGION">
- The region of your S3 server
-</ParamField>
+The stack bundles [Garage](https://garagehq.deuxfleurs.fr/) for file uploads, which works out of the box. To use an external S3-compatible service (AWS S3, Cloudflare R2, MinIO, etc.), set the variables below in `.env` β€” the bundled `garage` container is skipped automatically when `S3_ENDPOINT` points elsewhere.
<ParamField path="S3_ENDPOINT">
- The endpoint of your S3 server. Can be left empty if using AWS S3.
+ S3 API endpoint. Leave unset to use the bundled storage. Example: `https://s3.us-east-1.amazonaws.com`.
</ParamField>
-## Branding
-
-These options allow you to customize the branding of your Rallly instance. See [White Labeling](/self-hosting/white-labeling) for more details.
-
-<Note>
-These options are available from v4.6.0 and later and require an Enterprise license with a white-label add-on.
-</Note>
-
-<ParamField path="APP_NAME" default="Rallly">
- The name of your application. Appears in page titles, navigation, and emails.
-</ParamField>
-
-<ParamField path="PRIMARY_COLOR" default="#4f46e5">
- The primary brand color for light mode. Must be a valid hex color code.
-</ParamField>
-
-<ParamField path="PRIMARY_COLOR_DARK">
- The primary brand color for dark mode. Auto-calculated from `PRIMARY_COLOR` if not set.
+<ParamField path="S3_BUCKET_NAME">
+ Bucket name for uploads.
</ParamField>
-<ParamField path="LOGO_URL" default="/static/logo.svg">
- URL to your logo for light mode. SVG format recommended.
+<ParamField path="S3_REGION">
+ Bucket region (e.g. `us-east-1`, `auto` for Cloudflare R2).
</ParamField>
-<ParamField path="LOGO_URL_DARK">
- URL to your logo for dark mode. Falls back to `LOGO_URL` if not set.
+<ParamField path="S3_ACCESS_KEY_ID">
+ Access key for the bucket.
</ParamField>
-<ParamField path="LOGO_ICON_URL" default="/images/rallly-logo-mark.png">
- URL to your logo icon used in emails and as a favicon.
+<ParamField path="S3_SECRET_ACCESS_KEY">
+ Secret key for the bucket.
</ParamField>
-
-<ParamField path="HIDE_ATTRIBUTION" default="false">
- Set to `true` to hide "Powered by Rallly" attribution in polls and emails.
-</ParamField>
\ No newline at end of file
diff --git a/apps/docs/self-hosting/installation/docker.mdx b/apps/docs/self-hosting/installation/docker.mdx
index 9c92ae959..93ec7f11b 100644
--- a/apps/docs/self-hosting/installation/docker.mdx
+++ b/apps/docs/self-hosting/installation/docker.mdx
@@ -1,125 +1,107 @@
---
-icon: docker
-title: Docker
-description: How to Self-Host Rallly using Docker
+icon: server
+title: Installation
+description: Install Rallly on your own server.
---
-This page will guide you through the process of setting up a self-hosted instance of Rallly using the Docker Compose configuration published in the [rallly-selfhosted](https://github.com/lukevella/rallly-selfhosted) repository on Github.
+This guide installs Rallly using the Docker Compose stack published in the [rallly-selfhosted](https://github.com/lukevella/rallly-selfhosted) repository. The stack includes the app, a bundled PostgreSQL database, bundled S3-compatible object storage, and an HTTPS reverse proxy β€” everything runs on one machine with no extra setup. If you'd rather use a managed database or object store, see [External services](#external-services).
-## Requirements
+<Note>
+ Already running Rallly from a hand-edited `docker-compose.yml` or `config.env`? Follow the [upgrade guide](/self-hosting/migration) to move onto the new stack without losing data.
+</Note>
-Before you get started you will need to have a server that has the following:
+## Requirements
-- Docker
+- A server with at least **2 GB RAM**
+- **Docker 19.03+** with **Compose v2**
+- Ports **80** and **443** open on the server (bundled proxy only β€” see [External reverse proxy](#external-reverse-proxy) if you're bringing your own)
+- A domain name with a DNS `A` record pointing to the server's IP
+- An **SMTP server** for sending emails (e.g. [Resend](https://resend.com), [Postmark](https://postmarkapp.com), [Mailgun](https://www.mailgun.com), [Brevo](https://www.brevo.com))
-_You will also need to have access to an SMTP server to send emails._
+<Note>
+ Use a transactional email provider. We don't recommend running your own SMTP server β€” deliverability depends on IP reputation, SPF/DKIM/DMARC, and reverse DNS, which are hard to get right. Consumer inboxes like Gmail or Proton Mail are also a poor fit: they rate-limit automated senders and will eventually block sign-in emails.
+</Note>
-## Setup Instructions
+## Quick install
-### 1. Clone the repository
+Run the installer on your server:
```sh
-git clone https://github.com/lukevella/rallly-selfhosted.git
-cd rallly-selfhosted
+curl -fsSL https://get.rallly.co | bash
```
-If you don't have `git` installed you can download the repo using `curl`
+The installer will:
-```sh
-curl -L https://github.com/lukevella/rallly-selfhosted/archive/master.tar.gz | tar -xz
-cd rallly-selfhosted-main
-```
+1. Check that Docker and the required ports are available.
+2. Download the stack to `/opt/rallly`.
+3. Walk you through configuration (domain, support email, SMTP).
+4. Generate secure secrets automatically.
+5. Start the stack.
-### 2. Add required config
+On first boot, Traefik will request a Let's Encrypt certificate for your domain. This can take up to a minute. Once it's ready, your instance is available at `https://<your-domain>`.
-In the root of this project you will find a file called `config.env`.
-This is where you can set your environment variables to configure your instance.
-This guide will go through the basics but, you can check out the full list of [configuration options](/self-hosting/configuration-options) in the [self-hosting docs](https://support.rallly.co/self-hosting).
+## Manual install
-Start by generating a secret key. **Must be at least 32-characters long**.
+If you prefer to review the stack before starting it:
```sh
-openssl rand -base64 32
+git clone https://github.com/lukevella/rallly-selfhosted.git
+cd rallly-selfhosted
+./rallly.sh setup
+./rallly.sh start
```
-Open `config.env` and set `SECRET_PASSWORD` to your secret key.
-
-Next, set `NEXT_PUBLIC_BASE_URL`. It should be the base url where this instance is accessible, including the scheme (eg. `http://` or `https://`), the domain name, and optionally a port. **Do not use trailing slashes or URLs with paths/subfolders.**.
-
-### 3. Configure your SMTP Server
+`./rallly.sh setup` runs the same interactive configuration as the quick installer and writes a `.env` file. You can also copy `.env.example` to `.env` and fill it in by hand.
-First, set `SUPPORT_EMAIL`. Your users will see this as the contact email for any support issues and it will also appear as the sender of all emails.
+<Note>
+ Only edit `.env` when configuring your instance. Modifying `docker-compose.yml`, `rallly.sh`, or other stack files may cause conflicts when you run `./rallly.sh update`.
+</Note>
-Next, use the following environment variables to configure your SMTP server:
+## Claim the admin account
-- `SMTP_HOST` - The host address of your SMTP server
-- `SMTP_PORT` - The port of your SMTP server
-- `SMTP_SECURE` - Set to "true" if SSL is enabled for your SMTP connection
-- `SMTP_USER` - The username (if auth is enabled)
-- `SMTP_PWD` - The password (if auth is enabled)
+After the stack is running, the first user whose email matches `INITIAL_ADMIN_EMAIL` can navigate to `/control-panel` and claim the admin role. See the [Control Panel guide](/self-hosting/control-panel) for details.
-### 4. Secure your instance
+## External services
-By default, anyone can register and login on your instance.
-You can restrict users by setting `ALLOWED_EMAILS`.
+The bundled reverse proxy, Postgres database, and object storage containers are the default. You can swap any of them for external providers (your own Nginx/Caddy/Cloudflare Tunnel, managed Postgres, AWS S3, Cloudflare R2, MinIO, etc.) by setting the relevant variables in `.env`. The installer uses Docker Compose profiles to skip any bundled service that has an external endpoint configured, so no stack edits are needed.
-If only you are planning on using this instance you can set `ALLOWED_EMAILS` to your email address.
-
-```
-ALLOWED_EMAILS="[email protected]"
-```
+### External reverse proxy
-If you would like to allow multiple users, you separate each email address with a comma.
+Set `PROXY_MODE=external` to disable the bundled Traefik. The `web` container is then published on a host port that your reverse proxy can route to. `WEB_PORT` controls the bind β€” defaults to `127.0.0.1:3000` (loopback only).
-```
+```env
+PROXY_MODE=external
+WEB_PORT=127.0.0.1:3000
```
-You can also use wildcards to allow all emails from a domain.
+Your reverse proxy is responsible for terminating TLS and forwarding to `WEB_PORT`. Set `WEB_PORT=0.0.0.0:3000` to expose on all interfaces, or pick a different port if 3000 is in use.
-```
-ALLOWED_EMAILS="*@example.com"
-```
+The installer prompts for this during `./rallly.sh setup` β€” pick option 2 ("external") at the reverse proxy step.
-### 6. Start the server
+### External database
-You can start the server by running:
+Set `DATABASE_URL` in `.env` to your Postgres connection string. When this variable is set, the bundled `db` container is not started.
+```env
+DATABASE_URL=postgres://user:[email protected]:5432/rallly
```
-docker compose up -d
-```
-
-This command will:
-
-- Create a postgres database
-- Run migrations to set up the database schema
-- Start the Next.js server on port 3000
-
-## Using a Reverse Proxy
-By default the app will run unencrypted on port 3000. If you want to serve the app over HTTPS you will need to use a reverse proxy.
+### External object storage
-After setting up a reverse proxy be sure to change this line `- 3000:3000` to - `127.0.0.1:3000:3000` in `docker-compose.yml` and restart the container for it to apply the changes. This prevents Rallly from being accessed remotely using HTTP on port 3000 which is a security concern.
+Set the S3 variables in `.env` to point at your bucket. When `S3_ENDPOINT` is set to anything other than the bundled Garage endpoint, the bundled `garage` container is not started.
-## Version Management
-
-Rallly uses semantic versioning and releases are published as tags on [Docker Hub](https://hub.docker.com/r/lukevella/rallly).
-You can use `latest` to get the most recent release but it is recommended that you pin the image to a major version to avoid accidentally pulling in breaking changes.
-You can set the version in `docker-compose.yml` by changing the following line:
-
-```
-- image: lukevella/rallly:<version>
+```env
+S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
+S3_BUCKET_NAME=my-rallly-bucket
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=...
+S3_SECRET_ACCESS_KEY=...
```
-Check the [releases](https://github.com/lukevella/rallly/releases) to see what versions are available.
-We follow semver versioning so you may want to set your version to a major release (e.g. `lukevella/rallly:3`) to avoid pulling in breaking changes.
+Apply changes with `./rallly.sh restart`.
-## Update Instructions
+## Next steps
-Rallly is constantly being updated but you will need to manually pull these updates and restart the server to run the latest version. You can do this by running the following commands from within the same directory as your `docker-compose.yml`:
-
-```sh
-docker compose down
-docker compose pull
-docker compose up -d
-```
+- **[Configuration](/self-hosting/configuration)** β€” full environment variable reference.
+- **[Management](/self-hosting/management)** β€” updating, backups, and day-to-day operations.
+- **[Single Sign-On](/self-hosting/single-sign-on)** β€” enable Google, Microsoft, or OIDC login.
diff --git a/apps/docs/self-hosting/introduction.mdx b/apps/docs/self-hosting/introduction.mdx
index 468868791..850a0dc11 100644
--- a/apps/docs/self-hosting/introduction.mdx
+++ b/apps/docs/self-hosting/introduction.mdx
@@ -1,32 +1,40 @@
---
icon: "house"
title: "Introduction"
-description: "Learn how to set up and manage your own instance of Rallly."
+description: "Self-host Rallly on your own infrastructure."
---
-Self-hosting Rallly gives you complete control over your instance and your data. You can customize it to your needs, integrate it within your own infrastructure, and manage user access directly.
+Self-hosting Rallly gives you full control over your instance and your data. The self-hosted distribution is designed to be easy to install and maintain on a single server β€” everything you need is bundled into one Docker Compose stack.
-## The Official Docker Image
+## Rallly Cloud vs Rallly Self-Hosted
-The primary and **officially supported method** for self-hosting Rallly is by using our **official Docker image**. This image contains a build specifically optimized for self-hosting, with features like billing automatically disabled and no feature-gating.
+Rallly comes in two flavours built from the same codebase.
-These guides will walk you through using the Docker image:
+**[Rallly Cloud](https://rallly.co)** is the hosted service we run. It is designed to scale horizontally across distributed infrastructure and serve a large number of users. It is the fastest way to get started and is maintained by us.
-* **[Installation](/self-hosting/installation/docker):** Setting up Rallly using Docker.
-* **[Configuration](/self-hosting/configuration):** Customizing your instance with environment variables.
-* **[Licensing](/self-hosting/licensing):** Understanding when a license is needed and how to manage it.
-* **[Control Panel](/self-hosting/control-panel):** Managing your instance, users, and settings.
+**Rallly Self-Hosted** is optimised for simplicity of deployment. Out of the box, the application, database, object storage, and TLS termination all run on a single machine via Docker Compose β€” you own the data, you own the server, and updates are a single command. If you already run a managed Postgres or S3-compatible service, you can point Rallly at those instead and the bundled containers are skipped automatically.
<Note>
- While Rallly's source code is publicly available, self-hosting directly from the source code is not officially supported. For a stable and optimized experience, please use the provided Docker image.
+ Some Cloud features (billing, metered quotas) are compiled out of the self-hosted image. Licensing for multi-user self-hosted instances is covered on the [Licensing page](/self-hosting/licensing).
</Note>
-## Licensing
+## What's included
-Rallly is free to self-host for **personal, single-user setups**. For instances with **multiple users**, we ask that you purchase a license. This helps support the ongoing development and maintenance of Rallly. You can find more details about the different tiers and how to purchase a license on our [Licensing page](/self-hosting/licensing).
+A self-hosted install is a batteries-included stack. You do not need to provision these services separately.
-## Before You Begin
+- **Traefik** β€” reverse proxy with automatic HTTPS via Let's Encrypt
+- **Rallly** β€” the web application
+- **PostgreSQL** β€” primary database
+- **Garage** β€” S3-compatible object storage for file uploads
-Ensure you have a basic understanding of Docker and server management. While we aim to make the process straightforward, some technical knowledge is beneficial.
+Only Traefik binds to host ports (80 and 443). Everything else is isolated on the internal Docker network.
-If you're not ready to self-host or prefer a managed solution, you can always use the official Rallly service at [rallly.co](https://rallly.co).
\ No newline at end of file
+## Next steps
+
+- **[Installation](/self-hosting/installation/docker)** β€” set up Rallly on your server.
+- **[Configuration](/self-hosting/configuration)** β€” environment variables reference.
+- **[Management](/self-hosting/management)** β€” update, back up, and operate your instance.
+- **[Control Panel](/self-hosting/control-panel)** β€” manage users and instance settings.
+- **[Licensing](/self-hosting/licensing)** β€” when a license is needed and how to apply one.
+
+If you would rather not run a server, use [Rallly Cloud](https://rallly.co).
diff --git a/apps/docs/self-hosting/management.mdx b/apps/docs/self-hosting/management.mdx
new file mode 100644
index 000000000..809178b6f
--- /dev/null
+++ b/apps/docs/self-hosting/management.mdx
@@ -0,0 +1,122 @@
+---
+icon: terminal
+title: Management
+description: Operate a self-hosted Rallly instance with the rallly.sh CLI.
+---
+
+The `rallly.sh` script bundled with the [self-hosted stack](https://github.com/lukevella/rallly-selfhosted) is the single entry point for day-to-day operations. Run it from the stack directory (e.g. `/opt/rallly` for installer-based setups).
+
+## Commands
+
+```sh
+./rallly.sh start # Start all services
+./rallly.sh stop # Stop all services
+./rallly.sh restart # Restart all services
+./rallly.sh status # Show service status
+./rallly.sh logs # Stream logs for all services
+./rallly.sh logs web # Stream logs for a specific service
+./rallly.sh update # Pull latest images and recreate containers
+./rallly.sh backup # Back up the database to ./backups/
+```
+
+## Applying configuration changes
+
+After editing `.env`, apply changes with:
+
+```sh
+./rallly.sh restart
+```
+
+## Updating
+
+```sh
+./rallly.sh update
+```
+
+This pulls the latest Docker images and recreates containers. Your data and configuration are preserved.
+
+By default the stack tracks the `lukevella/rallly:4` tag, so `update` will bring you the latest compatible `4.x` release. To pin to a specific version or follow a different major, set `RALLLY_IMAGE` in `.env` (see [Configuration](/self-hosting/configuration#advanced)).
+
+<Warning>
+ Do not edit `docker-compose.yml` or other stack files. `./rallly.sh update` expects these files unchanged and will overwrite local edits. Only `.env` is safe to modify.
+</Warning>
+
+## Backup and restore
+
+### Backup
+
+```sh
+./rallly.sh backup
+```
+
+Database backups are written to `./backups/` as timestamped `.sql.gz` files. Copy these off the server regularly β€” they are your main recovery artifact.
+
+<Note>
+ The backup captures the PostgreSQL database. Uploaded files (avatars, etc.) are stored in the `garage-data` Docker volume; back that up separately if you rely on uploads.
+</Note>
+
+### Restore
+
+Stop the app first so it releases its database connections, drop and recreate an empty `rallly` database, stream in the dump, then restart:
+
+```sh
+# Stop the app (leave the db service running)
+docker compose stop web
+
+# Drop and recreate the database β€” connect to the "postgres" db so we can drop "rallly"
+docker compose exec -T db psql -U postgres -d postgres -c "DROP DATABASE IF EXISTS rallly;"
+docker compose exec -T db psql -U postgres -d postgres -c "CREATE DATABASE rallly;"
+
+# Restore β€” ON_ERROR_STOP=1 fails fast on the first error instead of continuing silently
+gunzip < backups/rallly_20260101_120000.sql.gz | docker compose exec -T db psql -v ON_ERROR_STOP=1 -U postgres rallly
+
+# Bring the app back up
+./rallly.sh start
+```
+
+## Logs
+
+Stream all services:
+
+```sh
+./rallly.sh logs
+```
+
+Or a single service (`web`, `db`, `garage`, `traefik`):
+
+```sh
+./rallly.sh logs web
+./rallly.sh logs traefik
+```
+
+## Troubleshooting
+
+### SSL certificate is not being issued
+
+Let's Encrypt can take up to a minute on first start. Check:
+
+- The domain's DNS `A` record resolves to the server's public IP.
+- Ports 80 and 443 are open in the server's firewall.
+- `./rallly.sh logs traefik` for ACME errors.
+
+### Port 80 or 443 already in use
+
+Another service (nginx, apache, another Docker stack) is bound to the port. Stop it or reconfigure it to leave 80/443 free β€” Traefik needs both.
+
+### Containers keep restarting
+
+Check the failing service's logs:
+
+```sh
+./rallly.sh logs web
+./rallly.sh logs db
+```
+
+Common causes:
+
+- Missing or invalid `.env` values (e.g. empty `SECRET_PASSWORD`, unreachable SMTP).
+- Database is still initialising on first boot β€” usually resolves within a few retries.
+
+### Database connection errors on first boot
+
+PostgreSQL takes a few seconds to initialise. The app retries automatically. If errors persist, inspect `./rallly.sh logs db`.
diff --git a/apps/docs/self-hosting/migration.mdx b/apps/docs/self-hosting/migration.mdx
new file mode 100644
index 000000000..ea4332a24
--- /dev/null
+++ b/apps/docs/self-hosting/migration.mdx
@@ -0,0 +1,156 @@
+---
+icon: arrow-right-arrow-left
+title: Upgrading from the legacy stack
+description: Move an existing self-hosted instance onto the new Docker stack.
+---
+
+Starting with **v4.10**, Rallly Self-Hosted ships as a managed Docker Compose stack with an installer, `rallly.sh` CLI, bundled reverse proxy (Traefik), and bundled object storage (Garage). If you set up Rallly before v4.10 β€” with a hand-edited `docker-compose.yml`, your own reverse proxy, or a `config.env` file β€” this guide walks you through the upgrade.
+
+<Warning>
+ This guide assumes you will tear down the old stack and run the new stack on the same server. Read every step before starting. A database backup is mandatory.
+</Warning>
+
+## Before you begin
+
+- You have **root (or sudo) access** to the server.
+- You have a **recent, tested database backup** stored off the server.
+- Your DNS `A` record for the domain points at this server's IP. Traefik will request a fresh Let's Encrypt certificate on first boot.
+
+## Step 1 β€” Save your secrets
+
+Open your existing `.env` or `config.env`. Copy these values somewhere safe β€” you'll paste them into the new stack's `.env`:
+
+| Value | Notes |
+|---|---|
+| `SECRET_PASSWORD` | **Critical.** Must carry over. Encrypts sessions; if it changes, all existing sessions are invalidated. |
+| `SUPPORT_EMAIL` | |
+| `NOREPLY_EMAIL` | If set. |
+| `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PWD` | All SMTP config. |
+| `ALLOWED_EMAILS` | If set. |
+| `INITIAL_ADMIN_EMAIL` | If set. |
+| `OIDC_*`, `GOOGLE_*`, `MICROSOFT_*` | Any SSO credentials you use. |
+
+Your domain (previously in `NEXT_PUBLIC_BASE_URL`) becomes `DOMAIN` in the new stack β€” **without the scheme or trailing slash**. For example `https://rallly.example.com` β†’ `rallly.example.com`.
+
+## Step 2 β€” Back up the database
+
+From your existing stack directory, with the old stack running:
+
+```sh
+docker compose exec -T rallly_db pg_dump -U postgres rallly | gzip > rallly-backup.sql.gz
+```
+
+Copy `rallly-backup.sql.gz` off the server (e.g. `scp` to your laptop). Do not skip this.
+
+<Note>
+ `rallly_db` is the Postgres service name in the official legacy `docker-compose.yml`. If you renamed it or authored your own compose file, replace it with whatever yours is called (run `docker compose ps` to check).
+</Note>
+
+## Step 3 β€” Stop the old stack
+
+From the old stack directory:
+
+```sh
+docker compose down
+```
+
+If you were running an external reverse proxy (Nginx, Caddy, Apache) in front of Rallly, **stop and disable it now** β€” Traefik needs ports 80 and 443.
+
+```sh
+# Examples, adjust to your setup
+sudo systemctl stop nginx && sudo systemctl disable nginx
+sudo systemctl stop caddy && sudo systemctl disable caddy
+```
+
+Verify the ports are free:
+
+```sh
+sudo ss -tlnp | grep -E ':(80|443)\b'
+```
+
+Should return nothing.
+
+## Step 4 β€” Install the new stack
+
+```sh
+curl -fsSL https://get.rallly.co | bash
+```
+
+When prompted, **use the same `DOMAIN` as before**. For `SUPPORT_EMAIL`, SMTP settings, etc., paste in the values you saved in Step 1.
+
+After setup completes, **do not start the stack yet**. Edit `/opt/rallly/.env` and:
+
+1. Replace the freshly-generated `SECRET_PASSWORD` with the value from your old `.env`.
+2. Add any SSO variables (`OIDC_*`, `GOOGLE_*`, `MICROSOFT_*`) that the interactive setup didn't cover.
+
+See the full [configuration reference](/self-hosting/configuration).
+
+## Step 5 β€” Start the stack and restore the database
+
+```sh
+cd /opt/rallly
+./rallly.sh start
+```
+
+Wait for the database to finish initialising (about 10 seconds). Check with:
+
+```sh
+./rallly.sh logs db
+```
+
+Once you see `database system is ready to accept connections`, restore your backup:
+
+```sh
+# Stop the app so it releases its connections to the rallly database
+docker compose stop web
+
+# Drop the freshly-migrated empty database and recreate it β€” connect to "postgres" to drop "rallly"
+docker compose exec -T db psql -U postgres -d postgres -c "DROP DATABASE IF EXISTS rallly;"
+docker compose exec -T db psql -U postgres -d postgres -c "CREATE DATABASE rallly;"
+
+# Restore β€” ON_ERROR_STOP=1 fails fast on the first error instead of continuing silently
+gunzip < /path/to/rallly-backup.sql.gz | docker compose exec -T db psql -v ON_ERROR_STOP=1 -U postgres rallly
+```
+
+Start the app so it picks up the restored schema:
+
+```sh
+./rallly.sh start
+```
+
+## Step 6 β€” Verify
+
+1. Visit `https://<your-domain>`. You should see the sign-in page served over HTTPS (Traefik's Let's Encrypt certificate will be issued within a minute of first boot).
+2. Sign in with an existing account. If `SECRET_PASSWORD` was preserved correctly, your previous session may even still be valid.
+3. Open an existing poll and confirm votes are intact.
+4. Send a test sign-in email to confirm SMTP works.
+5. If you use SSO, sign in through each configured provider.
+
+If anything is missing or broken, **do not delete the old stack's volumes yet**. You can roll back by stopping the new stack and restarting the old one.
+
+## Step 7 β€” Clean up
+
+Once you're satisfied the new stack is working:
+
+```sh
+# Remove the old stack directory
+rm -rf /path/to/old/rallly-selfhosted
+
+# Remove orphaned Docker volumes from the old stack
+docker volume ls
+docker volume rm <old-volume-name>
+```
+
+<Warning>
+ Double-check volume names before removing. The new stack's volumes are prefixed with its Docker Compose project name, so confirm the prefix before deleting anything. The project name comes from `COMPOSE_PROJECT_NAME`, an explicit `name:` in `docker-compose.yml`, or the directory the compose file lives in. From inside the new stack's directory, run `docker compose config --format json | jq -r .name` to print it, or `docker compose ls` to list running projects and their volumes.
+</Warning>
+
+## What doesn't carry over
+
+- **TLS certificates.** Traefik issues fresh certificates via Let's Encrypt on first start. Any existing certs (from certbot or your old proxy) are not imported.
+- **Custom `docker-compose.yml` changes.** The new stack is managed; edits will conflict with `./rallly.sh update`. Configure via `.env` only.
+- **Uploaded files from an external S3 bucket.** The new stack ships with [Garage](https://garagehq.deuxfleurs.fr/) for uploads. If you were previously using external S3, either keep pointing at it (advanced, see [External object storage](/self-hosting/configuration#external-object-storage)) or accept that previously uploaded files will not appear in the new Garage instance.
+
+## Moving to a different server
+
+If you're migrating to a new server rather than upgrading in place, the flow is the same, with one change: complete Step 4 (install new stack) on the new server, then update your DNS `A` record to point at it before Step 5. Keep the old server running until Step 6 verification passes, which gives you a rollback path.
diff --git a/apps/docs/self-hosting/single-sign-on.mdx b/apps/docs/self-hosting/single-sign-on.mdx
index 228ee4437..bea0d75f1 100644
--- a/apps/docs/self-hosting/single-sign-on.mdx
+++ b/apps/docs/self-hosting/single-sign-on.mdx
@@ -1,72 +1,113 @@
---
icon: cloud
-title: Single Sign On (SSO)
-description: How to use your own identity provider
+title: Single Sign-On (SSO)
+description: Sign in with Google, Microsoft, or any OpenID Connect provider.
---
<Info>Available in v3.4.0 and later.</Info>
+Rallly supports three SSO options: Google, Microsoft (Entra ID), and any provider that speaks OpenID Connect (OIDC). You can enable more than one at a time.
+
<Warning>
- Accounts using the same email are linked together. This assumes that you are
- using a trusted identity provider that uses verified email addresses.
+ Accounts using the same email address are linked together. This assumes your identity provider only issues verified email addresses.
</Warning>
-## OpenID Connect (OIDC)
+## Google
-If your identity provider supports OAuth 2.0 based authentication with OpenID Connect (OIDC), you can use it to authenticate users on your Rallly instance.
+<Accordion title="Setup">
+1. Open the Google Cloud Credentials tab: https://console.developers.google.com/apis/credentials
-### Required Scopes
+2. Create an OAuth client ID. This gives you a `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.
-Your OAuth 2.0 application needs to be configured with the following scopes:
+3. Set **Authorized redirect URIs** to include your full domain and the callback path:
-- `openid`: Essential for OIDC to function, used to perform authentication.
-- `profile`: Access to the user's personal information such as name and picture.
-- `email`: Access to the user's email address.
+```
+https://<YOUR_DOMAIN>/api/auth/callback/google
+```
+</Accordion>
-### Callback URL / Redirect URI
+<ParamField path="GOOGLE_CLIENT_ID">
+ The client ID of your Google application.
+</ParamField>
+
+<ParamField path="GOOGLE_CLIENT_SECRET">
+ The client secret of your Google application.
+</ParamField>
-Your identity provider should redirect the user back to the following URL:
+## Microsoft
+
+<Accordion title="Setup">
+Follow the [Microsoft Entra ID quickstart](https://docs.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) to register an application.
+
+After creating the application, set the redirect URI to:
```
-{BASE_URL}/api/auth/callback/oidc
+https://<YOUR_DOMAIN>/api/auth/callback/microsoft-entra-id
```
+</Accordion>
+
+<ParamField path="MICROSOFT_TENANT_ID">
+ The tenant ID of your Microsoft application.
+</ParamField>
+
+<ParamField path="MICROSOFT_CLIENT_ID">
+ The client ID of your Microsoft application.
+</ParamField>
-<Info>
- Replace `{BASE_URL}` with the base URL of your Rallly instance and add it to
- the list of allowed redirect URIs.
-</Info>
+<ParamField path="MICROSOFT_CLIENT_SECRET">
+ The client secret of your Microsoft application.
+</ParamField>
+
+## OpenID Connect (OIDC)
+
+If your identity provider supports OAuth 2.0 with OpenID Connect, you can use it to authenticate users on your Rallly instance.
+
+### Required scopes
+
+Your OAuth 2.0 application needs these scopes:
+
+- `openid` β€” perform authentication (required).
+- `profile` β€” access name and picture.
+- `email` β€” access the user's email address.
+
+### Callback URL
+
+Your identity provider should redirect the user back to:
+
+```
+https://<YOUR_DOMAIN>/api/auth/callback/oidc
+```
### Configuration
-The following configuration options are available for OIDC.
All required fields must be set for OIDC to be enabled.
<ParamField path="OIDC_NAME" default="OpenID Connect">
- The display name of your provider as it will be shown on the login page
+ Display name of your provider as shown on the login page.
</ParamField>
<ParamField path="OIDC_DISCOVERY_URL" required>
- URL of the `.well-known/openid-configuration` endpoint for your OIDC provider
+ URL of the `.well-known/openid-configuration` endpoint for your OIDC provider.
</ParamField>
<ParamField path="OIDC_CLIENT_ID" required>
- The client ID of your OIDC application
+ The client ID of your OIDC application.
</ParamField>
<ParamField path="OIDC_CLIENT_SECRET" required>
- The client secret of your OIDC application
+ The client secret of your OIDC application.
</ParamField>
<ParamField path="OIDC_NAME_CLAIM_PATH" default="name">
- The path to the claim that contains the user's name
+ Path to the claim that contains the user's name.
</ParamField>
<ParamField path="OIDC_EMAIL_CLAIM_PATH" default="email">
- The path to the claim that contains the user's email address
+ Path to the claim that contains the user's email address.
</ParamField>
<ParamField path="OIDC_PICTURE_CLAIM_PATH" default="picture">
- The path to the claim that contains the user's profile picture
+ Path to the claim that contains the user's profile picture.
</ParamField>
<Info>Use dot notation in `_CLAIM_PATH` fields to access nested objects.</Info>
diff --git a/apps/docs/self-hosting/white-labeling.mdx b/apps/docs/self-hosting/white-labeling.mdx
index 2d8891c60..9df3b400f 100644
--- a/apps/docs/self-hosting/white-labeling.mdx
+++ b/apps/docs/self-hosting/white-labeling.mdx
@@ -27,23 +27,17 @@ All white labeling options are configured via environment variables. See the [Co
## Example
-Here's an example of a complete white labeling configuration in your `docker-compose.yml`:
-
-```yaml
-services:
- rallly:
- image: lukevella/rallly:4
- environment:
- # ... other required environment variables ...
-
- # White labeling
- APP_NAME: "Acme Scheduler"
- PRIMARY_COLOR: "#0066cc"
- PRIMARY_COLOR_DARK: "#3399ff"
- LOGO_URL: "https://example.com/logo.svg"
- LOGO_URL_DARK: "https://example.com/logo-dark.svg"
- LOGO_ICON_URL: "https://example.com/icon.png"
- HIDE_ATTRIBUTION: "true"
+Add your white labeling values to the `.env` file at the root of your self-hosted stack, then apply them with `./rallly.sh restart`:
+
+```sh
+# White labeling
+APP_NAME="Acme Scheduler"
+PRIMARY_COLOR="#0066cc"
+PRIMARY_COLOR_DARK="#3399ff"
+LOGO_URL="https://example.com/logo.svg"
+LOGO_URL_DARK="https://example.com/logo-dark.svg"
+LOGO_ICON_URL="https://example.com/icon.png"
+HIDE_ATTRIBUTION="true"
```
## Viewing Current Settings