Revolt Self-Hosted

Self-hosting Revolt using Docker

This repository contains configurations and instructions that can be used for deploying Revolt.

Note

Please consult 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.

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.

Tip

We've partnered with Hostinger to bring you a 20% discount off VPS hosting!

👉 https://www.hostinger.com/vps-hosting?REFERRALCODE=REVOLTCHAT

We recommend using the KVM 2 plan at minimum!
Our testing environment for self-hosted currently sits on a KVM 2 instance and 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.

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:

You should set a secure root password for login (or disable password login after setup, which is explained later! but you shouldn't make the password trivial until after this is secured at least!) and we recommend that you configure an SSH key:

Make sure to confirm everything is correct!

Wait for your VPS to be created...

After install, SSH into the machine:

# use the provided IP address to connect:
ssh root@<ip address>
# .. if you have a SSH key configured
ssh root@<ip address> -i path/to/id_rsa

And now we can proceed with some basic configuration and securing the system:

# update the system
apt-get update && apt-get upgrade -y

# configure firewall
ufw allow ssh
ufw allow http
ufw allow https
ufw default deny
ufw enable

# if you have configured an SSH key, disable password authentication:
sudo sed -E -i 's|^#?(PasswordAuthentication)\s.*|\1 no|' /etc/ssh/sshd_config
if ! grep '^PasswordAuthentication\s' /etc/ssh/sshd_config; then echo 'PasswordAuthentication no' |sudo tee -a /etc/ssh/sshd_config; fi

# reboot to apply changes
reboot

Your system is now ready to proceed with installation, but before we continue you should configure your domain.

Your domain (or a subdomain) should point to the server's IP (A and AAAA records) or CNAME to the hostname provided.

Next, we must install the required dependencies:

# ensure Git and Docker are installed
apt-get update
apt-get install ca-certificates curl git micro
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

apt-get update
apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Now, we can pull in the configuration for Revolt:

git clone https://github.com/revoltchat/self-hosted revolt
cd revolt

Generate a configuration file by running:

./generate_config.sh your.domain

You can find more options here, some noteworthy configuration options:

• Email verification
• Captcha
• A custom S3 server

If you'd like to edit the configuration, just run:

micro Revolt.toml

Finally, we can start up Revolt:

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.

Pull the latest version of this repository:

git pull

Check if your configuration file is correct by opening the reference config file and your Revolt.toml and comparing for changes.

Then pull all the latest images:

docker compose pull

Then restart the services:

docker compose up

Additional Notes

Quick Start (for advanced users)

Prerequisites before continuing:

• Git
• Docker

Clone this repository.

git clone https://github.com/revoltchat/self-hosted revolt
cd revolt

Copy .env 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.

echo "HOSTNAME=http://local.revolt.chat" > .env.web
echo "REVOLT_PUBLIC_URL=http://local.revolt.chat/api" >> .env.web
wget -O Revolt.toml https://raw.githubusercontent.com/revoltchat/backend/main/crates/core/config/Revolt.toml

Then start Revolt:

docker compose up -d

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:

# .env
- REVOLT_APP_URL=http://local.revolt.chat
+ REVOLT_APP_URL=http://my.domain

# Revolt.toml
- app = "http://local.revolt.chat"
+ app = "http://my.domain"

You will also want to change the protocols to enable HTTPS:

# .env
- REVOLT_APP_URL=http://my.domain
+ REVOLT_APP_URL=https://my.domain

- REVOLT_EXTERNAL_WS_URL=ws://my.domain/ws
+ REVOLT_EXTERNAL_WS_URL=wss://my.domain/ws

# Revolt.toml
- app = "http://local.revolt.chat"
+ app = "https://my.domain"

- events = "ws://my.domain/ws"
+ events = "wss://my.domain/ws"

In the case of HOSTNAME, you must strip the protocol prefix:

# .env
- HOSTNAME=https://my.domain
+ HOSTNAME=my.domain

Putting Revolt behind another reverse proxy (or on a non-standard port)

Override the port definitions on caddy:

# compose.yml
services:
  caddy:
    ports:
      - "1234:80"

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.

Update the hostname used by the web server:

# .env
- HOSTNAME=http://local.revolt.chat
+ HOSTNAME=:80

You can now reverse proxy to http://localhost:1234.

Insecurely expose database

You can insecurely expose the database by adding a port definition:

# compose.override.yml
services:
  database:
    ports:
      - "27017:27017"

Mongo compatibility

Older processors may not support the latest MongoDB version, you may pin to MongoDB 4.4 as such:

# compose.override.yml
services:
  database:
    image: mongo:4.4

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.

Create an invite:

# drop into mongo shell
docker compose exec database mongosh

# create the invite
use revolt
db.invites.insertOne({ _id: "enter_an_invite_code_here" })

Notices

Important

If you deployed Revolt before 2022-10-29, you may have to tag the minio image release if it's configured in "fs" mode.

image: minio/minio:RELEASE.2022-10-24T18-35-07Z

Important

If you deployed Revolt before 2023-04-21, you may have to flush your Redis database.

# for stock Redis and older KeyDB images:
docker compose exec redis redis-cli
# ...or for newer KeyDB images:
docker compose exec redis keydb-cli

# then run:
FLUSHDB

Important

As of 30th September 2024, Autumn has undergone a major refactor which requires a manual migration.

To begin, add a temporary container that we can work from:

# compose.override.yml
services:
  migration:
    image: node:21
    volumes:
      - ./migrations:/cwd
    command: "bash -c 'while true; do sleep 86400; done'"

Then switch to the shell:

docker compose up -d database migration
docker compose exec migration bash

Now we can run the migration:

cd /cwd
npm i mongodb
node ./20240929-autumn-rewrite.mjs