📝 Update documentation (#1733)

This commit is contained in:
Luke Vella 2025-05-28 10:28:21 +01:00 committed by GitHub
parent 53a957dc49
commit b557084d9c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
13 changed files with 4401 additions and 186 deletions

View file

@ -11,7 +11,7 @@
"light": "#6366f1",
"dark": "#4F46E5",
"background": {
"light": "#F9FAFB",
"light": "#f3f4f6",
"dark": "#18181B"
},
"anchors": { "from": "#878AFA", "to": "#4347F1" }
@ -38,7 +38,7 @@
],
"navigation": [
{
"group": "Documentation",
"group": "Get Started",
"pages": ["introduction", "faq"]
},
{
@ -50,22 +50,26 @@
"pages": ["guide/participant-guide"]
},
{
"group": "Self-Hosting",
"group": "Get Started",
"pages": [
"self-hosting/introduction",
{
"icon": "bolt",
"group": "Get Started",
"pages": [
"self-hosting/docker-compose",
"self-hosting/single-sign-on",
"self-hosting/configuration-options"
]
"icon": "server",
"group": "Installation",
"pages": ["self-hosting/installation/docker"]
},
"self-hosting/pricing",
"self-hosting/managed-hosting"
"self-hosting/licensing",
"self-hosting/configuration"
]
},
{
"group": "Guides",
"pages": ["self-hosting/control-panel"]
},
{
"group": "Misc",
"pages": ["self-hosting/managed-hosting"]
},
{
"group": "Contribute",
"pages": ["contribute/introduction"]

View file

@ -2,7 +2,16 @@
"name": "@rallly/docs",
"version": "0.0.0",
"private": true,
"scripts": {
"dev": "mint dev",
"build": "mint build"
},
"devDependencies": {
"@rallly/tsconfig": "workspace:*"
},
"dependencies": {
"mint": "^4.1.33",
"react": "^19.1.0",
"react-dom": "^19.1.0"
}
}

View file

@ -1,77 +0,0 @@
---
icon: gear
title: Configuration Options
description: Using environment variable to configure a self-hosted instance of Rallly.
---
## Environment variables
An environment variable is a dynamic value that can be set outside of an application and is used to configure or customize the behavior of an application.
This page lists all environment variables supported by Rallly.
### Base Configuration
These variables need to be configured for Rallly to run and function properly.
<ParamField path="DATABASE_URL" required>
Postgres database connection string
</ParamField>
<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>
<ParamField path="SECRET_PASSWORD" required>
A random 32-character secret key used to encrypt user sessions
</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.
</ParamField>
### Email Configuration
These variables need to be configured to let Rallly send out transactional emails.
<ParamField path="NOREPLY_EMAIL">
This email is used as the sender for all transactional emails. If not set,
`SUPPORT_EMAIL` will be used instead.
</ParamField>
<ParamField path="NOREPLY_EMAIL_NAME">
This name is used as the sender name for all transactional emails. If not set,
`Rallly` will be used instead.
</ParamField>
<ParamField path="SUPPORT_EMAIL" required>
This email will be shown as the contact email for support queries.
</ParamField>
<ParamField path="SMTP_HOST">The host address of your SMTP server</ParamField>
<ParamField path="SMTP_PORT" default="25 or 465">
The port of your SMTP server
</ParamField>
<ParamField path="SMTP_SECURE" default="false">
Set to "true" if SSL is enabled for your SMTP connection
</ParamField>
<ParamField path="SMTP_USER" default="">
The username (if auth is enabled on your SMTP server)
</ParamField>
<ParamField path="SMTP_PWD" default="">
The password (if auth is enabled on your SMTP server)
</ParamField>
<ParamField path="SMTP_TLS_ENABLED" default={"false"}>
Enable TLS for your SMTP connection
</ParamField>
### Single Sign On (SSO)
Go to [Single Sign On](/self-hosting/single-sign-on) for information on how to configure SSO.

View file

@ -0,0 +1,186 @@
---
icon: gear
title: Configuration Options
description: Using environment variable to configure a self-hosted instance of Rallly.
---
## 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>
<ParamField path="SECRET_PASSWORD" required>
A random 32-character secret key used to encrypt user sessions
</ParamField>
<ParamField path="SUPPORT_EMAIL" required>
This email will be shown 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.
</ParamField>
<ParamField path="NOREPLY_EMAIL_NAME" default="Rallly">
This name is used as the 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
</ParamField>
## Email (SMTP)
<ParamField path="SMTP_HOST">The host address of your SMTP server</ParamField>
<ParamField path="SMTP_PORT" default="25 or 465">
The port of your SMTP server
</ParamField>
<ParamField path="SMTP_SECURE" default="false">
Set to "true" if SSL is enabled for your SMTP connection
</ParamField>
<ParamField path="SMTP_USER" default="">
The username (if auth is enabled on your SMTP server)
</ParamField>
<ParamField path="SMTP_PWD" default="">
The password (if auth is enabled on your SMTP server)
</ParamField>
<ParamField path="SMTP_TLS_ENABLED" default={"false"}>
Enable TLS for your SMTP connection
</ParamField>
## Auth
<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.
</ParamField>
### Google
<Accordion title="Setup">
1. Head over to the Credentials tab: https://console.developers.google.com/apis/credentials
2. Create a OAuth client ID. This will be your `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
3. Set "Authorized redirect URIs" to include your full domain and end in the callback path:
```
https://<YOUR_DOMAIN>/api/auth/callback/google
```
</Accordion>
<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>
### 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>
<ParamField path="MICROSOFT_CLIENT_ID">
The client ID of your Microsoft application
</ParamField>
<ParamField path="MICROSOFT_CLIENT_SECRET">
The client secret of your Microsoft application
</ParamField>
### Custom SSO (OIDC)
<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>
<ParamField path="OIDC_DISCOVERY_URL">
URL of the `.well-known/openid-configuration` endpoint for your OIDC provider
</ParamField>
<ParamField path="OIDC_CLIENT_ID">
The client ID of your OIDC application
</ParamField>
<ParamField path="OIDC_CLIENT_SECRET">
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
</ParamField>
<ParamField path="OIDC_EMAIL_CLAIM_PATH" default="email">
The 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
</ParamField>
<Info>Use dot notation in `_CLAIM_PATH` fields to access nested objects.</Info>
## Storage (S3)
<ParamField path="S3_BUCKET_NAME">
The name of your S3 bucket
</ParamField>
<ParamField path="S3_ACCESS_KEY_ID">
The access key ID of your S3 server
</ParamField>
<ParamField path="S3_SECRET_ACCESS_KEY">
The secret access key of your S3 server
</ParamField>
<ParamField path="S3_ENDPOINT">
The endpoint of your S3 server. Can be left empty if using AWS S3.
</ParamField>
<ParamField path="S3_REGION">
The region of your S3 server. Can be left empty if using AWS S3.
</ParamField>

View file

@ -0,0 +1,25 @@
---
title: "Accessing the Control Panel"
description: "Learn how to access and use the Control Panel to manage your self-hosted Rallly instance."
---
The Control Panel is your central hub for administering your self-hosted Rallly instance. From here, you can manage users, activate your license, and configure instance-specific settings.
To access the Control Panel:
1. Ensure your Rallly instance is running.
2. Open your web browser and navigate to `/control-panel`.
3. You may be prompted to log in if you haven't already. Only users with administrative privileges can access the Control Panel features, though all users can visit the page.
## Claiming Initial Admin Rights
The first user designated as an administrator needs to manually claim their admin role. This user is specified by the `INITIAL_ADMIN_EMAIL` environment variable during setup (see [Configuration](/self-hosting/configuration)).
To claim admin rights:
1. Ensure the user account associated with the `INITIAL_ADMIN_EMAIL` has been created (e.g., by logging in once).
2. Navigate to the Control Panel: `/control-panel`.
3. If you are the user specified in `INITIAL_ADMIN_EMAIL` and have not yet claimed admin rights, you should see a section or button prompting you to "Make me an admin".
4. Click this button to elevate your account to an administrator.
Once claimed, this user can manage other users and settings.

View file

@ -1,7 +1,7 @@
---
icon: docker
title: Docker Compose
description: How to Self-Host Rallly using Docker Compose
title: Docker
description: How to Self-Host Rallly using Docker
---
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.

View file

@ -1,53 +1,32 @@
---
icon: server
title: Introduction
description: How to Self-Host Rallly
icon: "house"
title: "Introduction"
description: "Learn how to set up and manage your own instance of Rallly."
---
Rallly is 100% open-source and available under the [GNU Affero General Public License v3.0 (AGPL-3.0)](https://github.com/lukevella/rallly/blob/main/LICENSE)
which allows you to run your own instance of Rallly for free for both personal and commercial use.
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.
<Frame>
<img src="/images/self-hosting/splash.png" alt="Rallly Splash Image" />
</Frame>
## The Official Docker Image
## Official Docker Image
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.
The best way to self-host Rallly is using the [official Docker image](https://hub.docker.com/r/lukevella/rallly).
This image contains a build that is specifically intended for self-hosting.
It is updated regularly but it is _not_ guaranteed to be up-to-date with the latest version of Rallly.
If you want to have access to the latest features and bug fixes, you should consider using the [official managed service](https://rallly.co).
These guides will walk you through using the Docker image:
* **[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.
<Note>
Though it is technically possible to build and run Rallly from its
[source-code](https://github.com/lukevella/rallly), it is not recommended and
we do not provide support for this.
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.
</Note>
## Live Demo
## Licensing
If you want to try out Rallly before self-hosting it, you can try the official managed service at [app.rallly.co](https://app.rallly.co).
This version differs slightly from the self-hosted version in that it allows guest users to create polls without having to create an account
and is updated more frequently but it's still a good way to get a feel for the app.
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).
## Pricing
## Before You Begin
Rallly is **completely free** to self-host but for users who wish to contribute to the project,
please check out the [pricing](/self-hosting/pricing) page.
Ensure you have a basic understanding of Docker and server management. While we aim to make the process straightforward, some technical knowledge is beneficial.
## Get Started
Depending on how comfortable you are with technical things, you can either run Rallly on your own server or choose a managed hosting provider that will do it for you.
<CardGroup cols={2}>
<Card title="Docker Setup" icon="docker" href="/self-hosting/docker-compose">
Host your own instance of Rallly on your own server using Docker.
</Card>
<Card
icon="cloud"
title="Using a hosting provider"
href="/self-hosting/managed-hosting"
>
Choose a provider that will install and run an instance of Rallly for you.
</Card>
</CardGroup>
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).

View file

@ -0,0 +1,37 @@
---
icon: "key"
title: "Licensing"
description: "Understand Rallly's self-hosting license requirements, tiers, and pricing."
---
Rallly is open-source and always free for personal use.
If you want to run a multi-user setup, we ask that you purchase a license key.
## Pricing
| Tier | User Limit | Price | |
|:-------------|:--------------|:------------|:-------------------------------------------------------|
| **Personal** | 1 user | Free | - |
| **Plus** | Up to 5 users | $49 | [Buy License](https://rallly.co/buy-license/plus) |
| **Organization** | Up to 50 users| ~\$499~ **$299** (Limited Time Offer) | [Buy License](https://rallly.co/buy-license/organization) |
| **Enterprise** | 50+ users | Custom | [Contact Us](/contact/support) |
<Note>
The license key you purchase is a **perpetual license specifically for Rallly v4.x versions**. This means your license will grant you access to all features and updates within the entire Rallly v4 series for the user tier you've selected.
</Note>
## Activating Your License
Once you have your license key, you can activate it in your self-hosted Rallly instance:
1. Log in to your Rallly instance as an administrator.
2. Navigate to the [Control Panel](/self-hosting/control-panel).
3. Select **License**.
4. Enter your license key in the provided field and click **Activate**.
Your instance will now be licensed for multi-user access according to your chosen tier.
## Questions?
If you have any questions about licensing, pricing, or which tier is right for you, please don't hesitate to [contact us](/contact/support).

View file

@ -1,5 +1,4 @@
---
icon: cloud
title: Managed Hosting
description: Using a managed hosting service to self-host Rallly.
---

View file

@ -1,55 +1,53 @@
---
icon: coins
title: Pricing
description: How much does it cost to self-host Rallly?
description: Free for personal use. Purchase a license key for multi-user setups.
---
Rallly is **completely free** to self-host.
But free software doesnt mean its without cost.
Someone has to develop, maintain, and support it.
If you find Rallly useful you can help support further development by paying a one-time fee.
Rallly is open-source and always free (as in beer) for personal use. If you want to enable multi-user support for your team or organization, youll need a license key. This one-time purchase helps fund ongoing development and ensures Rallly remains sustainable.
## Suggested Price
**Every license includes:**
- All updates for your purchased version
- One-time payment, no subscriptions
- Access to private support channels
We believe $56 is a very fair price for the time and effort that's gone into making this product.
It's also the cost of a yearly subscription to the [official managed service](https://rallly.co).
If you find Rallly useful and can afford to pay, please consider paying this amount.
## The Honor System
We do not strictly enforce user limits—if your instance exceeds the recommended user count, youll simply see a reminder to purchase a license. Your instance will continue to work without interruption.
We rely on your honesty and support to keep Rallly open source and sustainable. If you find Rallly valuable and your usage exceeds the free tier, please consider purchasing a license to help fund further development.
## Choose Your License
<CardGroup cols={2}>
<Card
title="Plus License"
href="https://rallly.co/api/buy-license?product=plus"
>
<strong>For small teams</strong><br/>
Up to 5 users
</Card>
<Card
title="Org License"
href="https://rallly.co/api/buy-license?product=org"
>
<strong>For organizations</strong><br/>
Up to 50 users
</Card>
</CardGroup>
<CardGroup cols={1}>
<Card
title="Pay $56"
icon="cart-shopping"
href="https://buy.stripe.com/aEU1856UgdSf5nqeV6"
>
One-time payment for Rallly Self-Hosted
</Card>
<Card
title="Enterprise License"
href="https://rallly.co/api/buy-license/enterprise"
>
<strong>For large organizations</strong><br/>
More than 50 users, custom support and offline license (optional)
</Card>
</CardGroup>
## Pay What You Want
---
Alternatively, you can choose to pay **any amount** you want. Your support is appreciated regardless of how much you are able to pay.
<CardGroup cols={3}>
<Card
icon="dollar-sign"
title="Pay in USD"
href="https://buy.stripe.com/5kAdURdiEeWj5nqeV4"
>
One-time payment
</Card>
<Card
icon="euro-sign"
title="Pay in EUR"
href="https://buy.stripe.com/aEU2c92E0aG33fi7sA"
>
One-time payment
</Card>
<Card
icon="sterling-sign"
title="Pay in GBP"
href="https://buy.stripe.com/fZeeYV2E0bK7g246ox"
>
One-time payment
</Card>
</CardGroup>
By supporting Rallly, you're helping to keep open source scheduling accessible to everyone. Have questions or need a custom license? [Contact us](mailto:support@rallly.co).

View file

@ -1,5 +1,5 @@
---
icon: key
icon: cloud
title: Single Sign On (SSO)
description: How to use your own identity provider
---

View file

@ -52,7 +52,7 @@ export default function LicensingThankYouPage() {
<li>
<Link
className="text-link"
href="https://support.rallly.co/self-hosted/licensing/apply-license"
href="https://support.rallly.co/self-hosted/licensing"
>
<Trans
i18nKey="licensingThankYouNextStepsApplyLicense"

4075
pnpm-lock.yaml generated

File diff suppressed because it is too large Load diff