This section covers the configuration options for self-hosted instances of Rallly, designed for system administrators and operators who deploy and manage their own servers. These settings customize core behaviors such as the accessible URL, contact emails, authentication methods (including Google, Microsoft, and custom OIDC providers), outgoing email delivery via SMTP, file storage with S3-compatible services, and instance branding. Proper configuration ensures secure access, reliable notifications, and tailored user experiences. For runtime management after initial setup, see the Control Panel. For user-facing preferences, refer to User Settings and Preferences. This fits within broader Self-Hosting and Administration topics.
Overview
Configuration options are set using environment variables before starting your self-hosted instance. They control foundational aspects like security, communication, and appearance. Changes typically require restarting the application to take effect. Grouped into categories for easy reference, these settings include required ones (marked below) that must be defined for the instance to function.
General Settings
These foundational settings define the instance’s accessibility, security, and contact details.
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| NEXT_PUBLIC_BASE_URL | Yes | None | Full URL (e.g., https://example.com) | The public base URL where users access the instance, including scheme (http:// or https://), domain, and optional port. Used in links, emails, and redirects. |
| SECRET_PASSWORD | Yes | None | 32-character random string | Secret key for encrypting user sessions. Generate a strong, unique value. |
| SUPPORT_EMAIL | Yes | None | Valid email address | Contact email displayed for support queries across the app and emails. |
| NOREPLY_EMAIL | No | Uses SUPPORT_EMAIL | Valid email address | Sender address for transactional emails (e.g., notifications). |
| NOREPLY_EMAIL_NAME | No | Rallly | Text string | Display name for the sender in transactional emails. |
| INITIAL_ADMIN_EMAIL | No | None | Valid email address | Email of the first user eligible for admin role. They must visit the Control Panel and claim it after startup. |
Database Settings
Configures the PostgreSQL database connection.
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| DATABASE_URL | Yes | None | Postgres connection string | Full connection string to your PostgreSQL database (e.g., postgresql://user:pass@host:port/db). |
Email (SMTP) Settings
Enables reliable delivery of notifications, invites, and magic links via an SMTP server.
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| SMTP_HOST | No | None | Hostname or IP | SMTP server address. |
| SMTP_PORT | No | None | Number (e.g., 587, 465, 25) | SMTP port; use 587 for STARTTLS, 465 for SSL, 25 for plain. |
| SMTP_SECURE | No | false | true or false | Enables SSL (typically for port 465). |
| SMTP_USER | No | Empty | Username string | SMTP authentication username. |
| SMTP_PWD | No | Empty | Password string | SMTP authentication password. |
| SMTP_REJECT_UNAUTHORIZED | No | true | true or false | Validates TLS certificates; set to false for self-signed certs (not for production). Available from v4.4.0+. |
| SMTP_TLS_ENABLED | No | N/A | true or false | < [!WARNING]> Deprecated; use SMTP_REJECT_UNAUTHORIZED=false instead. Ignored in recent versions. |
[!NOTE] Without SMTP, emails fall back to basic sending if possible, but features like invites may fail.
Auth Settings
Controls login methods, registration, and allowed users. Email login (magic links) is enabled by default.
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| EMAIL_LOGIN_ENABLED | No | true | true or false | Enables/disables email-based login. Disabling also blocks registration. Available from v4.4.0+. |
| REGISTRATION_ENABLED | No | true | true or false | Globally disables new user sign-ups (overrides UI settings). Requires email login. Available from v4.4.0+. |
| ALLOWED_EMAILS | No | None | Comma-separated emails or wildcards (e.g., user@example.com, *@company.com) | Restricts registration/login to matching emails. |
Google Authentication
To enable:
- Visit the Google Cloud Console credentials page.
- Create an OAuth 2.0 Client ID.
- Add authorized redirect URI: *https://
/api/auth/callback/google*.
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| GOOGLE_CLIENT_ID | No | None | Client ID string | Google OAuth client ID. |
| GOOGLE_CLIENT_SECRET | No | None | Secret string | Google OAuth client secret. |
Microsoft Authentication
To enable:
- Follow Microsoft’s app registration guide.
- Set redirect URI: *https://
/api/auth/callback/microsoft-entra-id*.
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| MICROSOFT_TENANT_ID | No | None | Tenant ID string | Microsoft Entra ID tenant. |
| MICROSOFT_CLIENT_ID | No | None | Client ID string | Microsoft client ID. |
| MICROSOFT_CLIENT_SECRET | No | None | Secret string | Microsoft client secret. |
Custom SSO (OIDC)
Requires OIDC_DISCOVERY_URL, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET. Configure your provider with scopes: openid, profile, email. Redirect URI: *https://
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| OIDC_NAME | No | OpenID Connect | Text string | Display name on login page. |
| OIDC_DISCOVERY_URL | No | None | URL to .well-known/openid-configuration | OIDC provider discovery endpoint. |
| OIDC_ISSUER_URL | No | N/A | URL | < [!WARNING]> Deprecated from v4.5.0; no longer used. |
| OIDC_CLIENT_ID | No | None | Client ID string | OIDC client ID. |
| OIDC_CLIENT_SECRET | No | None | Secret string | OIDC client secret. |
| OIDC_NAME_CLAIM_PATH | No | name | Dot-notation path (e.g., name) | Path to user’s name claim. |
| OIDC_EMAIL_CLAIM_PATH | No | Dot-notation path | Path to user’s email claim. | |
| OIDC_PICTURE_CLAIM_PATH | No | picture | Dot-notation path | Path to user’s profile picture claim. |
Storage (S3) Settings
Optional; enables user avatar uploads and other file features. Use MinIO for self-hosted or cloud providers like AWS S3.
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| S3_BUCKET_NAME | No | None | Bucket name | S3 bucket for files. |
| S3_ACCESS_KEY_ID | No | None | Access key | S3 access key. |
| S3_SECRET_ACCESS_KEY | No | None | Secret key | S3 secret key. |
| S3_REGION | No | None | Region string | S3 region. |
| S3_ENDPOINT | No | None (AWS default) | Custom endpoint URL | Non-AWS S3 endpoint. |
Branding Settings
Customizes appearance and naming. < [!NOTE]> Requires Enterprise license with white-label add-on (v4.6.0+).
| Setting | Required | Default | Accepted Values | Description |
|---|---|---|---|---|
| APP_NAME | No | Rallly | Text string | App name in titles, nav, emails. |
| PRIMARY_COLOR | No | #4f46e5 | Hex color code | Primary color (light mode). |
[!NOTE] See White Labeling for full details (linked in source, adapt to wiki).
Summary
- Configure via environment variables before deployment; restart to apply changes.
- Required settings: NEXT_PUBLIC_BASE_URL, SECRET_PASSWORD, SUPPORT_EMAIL, DATABASE_URL.
- Enable emails with SMTP, auth with providers like Google or OIDC, storage via S3, and branding for custom look.
- For admin tasks post-setup, visit Control Panel; manage user prefs in User Settings and Preferences; explore Billing and Subscriptions for licenses.
- Test configurations thoroughly, especially auth redirects matching your NEXT_PUBLIC_BASE_URL.