@ -15,18 +15,31 @@ Self-hosting Revolt using Docker
This repository contains configurations and instructions that can be used for deploying Revolt.
> [!IMPORTANT]
> If you are updating an instance from before November 28 2024, please see the [notices section](#notices) at the bottom of this readme!
> [!WARNING]
> If you are updating an instance from before November 28, 2024, please see the [notices section](#notices) at the bottom of this README!
> [!IMPORTANT]
> A list of security advisories is [provided at the bottom](#security-advisories).
> [!NOTE]
> Please consult _[What can I do with Revolt and how do I self-host?](https://developers.revolt.chat/faq.html#admonition-what-can-i-do-with-revolt-and-how-do-i-self-host)_ on our developer site for information about licensing and brand use.
> Please consult _[What can I do with Revolt, and how do I self-host?](https://developers.revolt.chat/faq.html#admonition-what-can-i-do-with-revolt-and-how-do-i-self-host)_ on our developer site for information about licensing and brand use.
> [!NOTE]
> amd64 builds are not currently available for the web client.
## Table of Contents
- [Deployment](#deployment)
- [Updating](#updating)
- [Advanced Deployment](#advanced-deployment)
- [Additional Notes](#additional-notes)
- [Custom Domain](#custom-domain)
- [Placing Behind Another Reverse-Proxy or Another Port](#placing-behind-another-reverse-proxy-or-another-port)
- [Insecurely Expose the Database](#insecurely-expose-the-database)
- [Mongo Compatibility](#mongo-compatibility)
- [Making Your Instance Invite-only](#making-your-instance-invite-only)
- [Notices](#notices)
- [Security Advisories](#security-advisories)
## Deployment
To get started, find yourself a suitable server to deploy onto, we recommend starting with at least 2 vCPUs and 2 GB of memory.
@ -37,17 +50,18 @@ To get started, find yourself a suitable server to deploy onto, we recommend sta
> We recommend using the _KVM 2_ plan at minimum! <br> Our testing environment for self-hosted currently sits on a KVM 2 instance and are happy to assist with issues.
> We recommend using the _KVM 2_ plan at minimum!\
> Our testing environment for self-hosted currently sits on a KVM 2 instance, and we are happy to assist with issues.
The instructions going forwards will use Hostinger as an example hosting platform, but you should be able to adapt these to other platforms if necessary. There are important details throughout.
The instructions going forward will use Hostinger as an example hosting platform, but you should be able to adapt these to other platforms as necessary. There are important details throughout.
When asked, choose **Ubuntu Server** as your operating system, this is used by us in production and we recommend its use.
When asked, choose **Ubuntu Server** as your operating system; this is used by us in production, and we recommend its use.
If you've chosen to go with Hostinger, they include integrated malware scanning which may be of interest:
If you've chosen to go with Hostinger, they include integrated malware scanning, which may be of interest:
@ -95,7 +109,7 @@ if ! grep '^PasswordAuthentication\s' /etc/ssh/sshd_config; then echo 'PasswordA
reboot
```
Your system is now ready to proceed with installation, but before we continue you should configure your domain.
Your system is now ready to proceed with installation, but before we continue, you should configure your domain.
@ -147,7 +161,13 @@ If you'd like to edit the configuration, just run:
micro Revolt.toml
```
Finally, we can start up Revolt:
Finally, we can start up Revolt. First, run it in the foreground with:
```bash
docker compose up
```
If it runs without any critical errors, you can stop it with <kbd>Ctrl<kbd> + <kbd>C</kbd> and run it detached (in the background) by appending `-d`.
```bash
docker compose up -d
@ -155,7 +175,7 @@ docker compose up -d
## Updating
Before updating, ensure you consult the notices at the top of this README to check if there are any important changes to be aware of**as well as** [the notices](#notices).
Before updating, ensure you consult the notices at the top of this README, **as well as** [the notices](#notices) at the bottom, to check if there are any important changes to be aware of.
Pull the latest version of this repository:
@ -163,7 +183,7 @@ Pull the latest version of this repository:
git pull
```
Check if your configuration file is correct by opening [the reference config file](https://github.com/revoltchat/backend/blob/df074260196f5ed246e6360d8e81ece84d8d9549/crates/core/config/Revolt.toml) and your `Revolt.toml`and comparing for changes.
Check if your configuration file is correct by opening [the reference config file](https://github.com/revoltchat/backend/blob/df074260196f5ed246e6360d8e81ece84d8d9549/crates/core/config/Revolt.toml) and your `Revolt.toml`to compare changes.
Then pull all the latest images:
@ -174,12 +194,12 @@ docker compose pull
Then restart the services:
```bash
docker compose up
docker compose up -d
```
## Additional Notes
## Advanced Deployment
### Quick Start (for advanced users)
This guide assumes you know your way around a Linux terminal and Docker.
Copy `.env` and download `Revolt.toml`, then modify them according to your requirements.
Create `.env.web` and download `Revolt.toml`, then modify them according to your requirements.
> [!WARNING]
> The default configurations are intended exclusively for testing and will only work locally. If you wish to deploy to a remote server, you **must** edit the URLs in `.env` and `Revolt.toml`. Please reference the section below on [configuring a custom domain](#custom-domain).
> The default configurations are intended exclusively for testing and will only work locally. If you wish to deploy to a remote server, you **must** edit the URLs in `.env.web` and `Revolt.toml`. Please reference the section below on [configuring a custom domain](#custom-domain).
To configure a custom domain, you will need to replace all instances of `local.revolt.chat` in the `Revolt.toml` and `.env` files, like so:
To configure a custom domain, you will need to replace *all* instances of `local.revolt.chat` in `Revolt.toml` and `.env.web` to your chosen domain (here represented as `example.com`), like so:
```diff
# .env
- REVOLT_APP_URL=http://local.revolt.chat
+ REVOLT_APP_URL=http://my.domain
# .env.web
- REVOLT_PUBLIC_URL=http://local.revolt.chat/api
+ REVOLT_PUBLIC_URL=http://example.com
```
```diff
# Revolt.toml
- app = "http://local.revolt.chat"
+ app = "http://my.domain"
+ app = "http://example.com"
```
You will also want to change the protocols to enable HTTPS:
In the case of `HOSTNAME`, you must strip the protocol prefix:
```diff
# .env
- REVOLT_APP_URL=http://my.domain
+ REVOLT_APP_URL=https://my.domain
# .env.web
- HOSTNAME=http://example.com
+ HOSTNAME=example.com
```
You will likely also want to change the protocols to enable HTTPS:
- REVOLT_EXTERNAL_WS_URL=ws://my.domain/ws
+ REVOLT_EXTERNAL_WS_URL=wss://my.domain/ws
```diff
# .env.web
- REVOLT_PUBLIC_URL=http://example.com
+ REVOLT_PUBLIC_URL=https://example.com
```
```diff
# Revolt.toml
- app = "http://local.revolt.chat"
+ app = "https://my.domain"
- app = "http://example.com"
+ app = "https://example.com"
- events = "ws://my.domain/ws"
+ events = "wss://my.domain/ws"
- events = "ws://example.com/ws"
+ events = "wss://example.com/ws"
```
In the case of `HOSTNAME`, you must strip the protocol prefix:
```diff
# .env
- HOSTNAME=https://my.domain
+ HOSTNAME=my.domain
```
### Placing Behind Another Reverse-Proxy or Another Port
### Putting Revolt behind another reverse proxy (or on a non-standard port)
If you'd like to place Revolt behind another reverse proxy or on a non-standard port, you'll need to edit `compose.yml`.
Override the port definitions on `caddy`:
@ -267,19 +287,19 @@ services:
```
> [!WARNING]
> This file is not Git ignored. It may be sufficient to use an override file, but that will not remove port 80 / 443 allocations.
> This file is not included in `.gitignore`. It may be sufficient to use an override file, but that will not remove port `80` / `443` allocations.
Update the hostname used by the web server:
```diff
# .env
- HOSTNAME=http://local.revolt.chat
# .env.web
- HOSTNAME=http://example.com
+ HOSTNAME=:80
```
You can now reverse proxy to http://localhost:1234.
You can now reverse proxy to <http://localhost:1234>.
### Insecurely expose database
### Insecurely Expose the Database
You can insecurely expose the database by adding a port definition:
@ -291,9 +311,11 @@ services:
- "27017:27017"
```
### Mongo compatibility
For obvious reasons, be careful doing this.
### Mongo Compatibility
Older processors may not support the latest MongoDB version, you may pin to MongoDB 4.4 as such:
Older processors may not support the latest MongoDB version; you may pin to MongoDB 4.4 as such:
```yml
# compose.override.yml
@ -302,9 +324,9 @@ services:
image: mongo:4.4
```
### Making your instance invite-only
### Making Your Instance Invite-only
Enable invite-only mode by setting `REVOLT_INVITE_ONLY` in `.env` to `1` and `invite_only` in `Revolt.toml` to `true`.
Enable invite-only mode by setting `invite_only` in `Revolt.toml` to `true`.
- (`2024-12-17`) [GHSA-7f9x-pm3g-j7p4 revoltchat/january: January service can call itself recursively causing heavy load](https://github.com/revoltchat/january/security/advisories/GHSA-7f9x-pm3g-j7p4)
- (`2024-12-17`) [GHSA-7f9x-pm3g-j7p4 revoltchat/january: January service can call itself recursively, causing heavy load.](https://github.com/revoltchat/january/security/advisories/GHSA-7f9x-pm3g-j7p4)
Declan Chidlow
3 weeks ago
committed by
GitHub