merge: pull request #112 from revoltchat/docs/new-guide

pull/114/head
Paul Makles 4 months ago committed by GitHub
commit 71e9b9579b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

@ -1,103 +0,0 @@
##
## Quark configuration
##
# MongoDB
MONGODB=mongodb://database
# Redis
REDIS_URI=redis://redis/
# Hostname used for Caddy
# This should in most cases match REVOLT_APP_URL
HOSTNAME=http://local.revolt.chat
# URL to where the Revolt app is publicly accessible
REVOLT_APP_URL=http://local.revolt.chat
# URL to where the API is publicly accessible
REVOLT_PUBLIC_URL=http://local.revolt.chat/api
VITE_API_URL=http://local.revolt.chat/api
# URL to where the WebSocket server is publicly accessible
REVOLT_EXTERNAL_WS_URL=ws://local.revolt.chat/ws
# URL to where Autumn is publicly available
AUTUMN_PUBLIC_URL=http://local.revolt.chat/autumn
# URL to where January is publicly available
JANUARY_PUBLIC_URL=http://local.revolt.chat/january
##
## hCaptcha Settings
##
# If you are sure that you don't want to use hCaptcha, set to 1.
REVOLT_UNSAFE_NO_CAPTCHA=1
# hCaptcha API key (This is the "Secret key" from your User Settings page)
# REVOLT_HCAPTCHA_KEY=0x0000000000000000000000000000000000000000
# hCaptcha site key
# REVOLT_HCAPTCHA_SITEKEY=10000000-ffff-ffff-ffff-000000000001
##
## Email Settings
##
# If you are sure that you don't want to use email verification, set to 1.
REVOLT_UNSAFE_NO_EMAIL=1
# SMTP host
# REVOLT_SMTP_HOST=smtp.example.com
# SMTP username
# REVOLT_SMTP_USERNAME=noreply@example.com
# SMTP password
# REVOLT_SMTP_PASSWORD=CHANGEME
# SMTP From header
# REVOLT_SMTP_FROM=Revolt <noreply@example.com>
##
## Application Settings
##
# Whether to only allow users to sign up if they have an invite code
REVOLT_INVITE_ONLY=0
# Maximum number of people that can be in a group chat
REVOLT_MAX_GROUP_SIZE=150
# VAPID keys for push notifications
# Generate using this guide: https://gitlab.insrt.uk/revolt/delta/-/wikis/vapid
# --> Please replace these keys before going into production! <--
REVOLT_VAPID_PRIVATE_KEY=LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUJSUWpyTWxLRnBiVWhsUHpUbERvcEliYk1yeVNrNXpKYzVYVzIxSjJDS3hvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFWnkrQkg2TGJQZ2hEa3pEempXOG0rUXVPM3pCajRXT1phdkR6ZU00c0pqbmFwd1psTFE0WAp1ZDh2TzVodU94QWhMQlU3WWRldVovWHlBdFpWZmNyQi9BPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
REVOLT_VAPID_PUBLIC_KEY=BGcvgR-i2z4IQ5Mw841vJvkLjt8wY-FjmWrw83jOLCY52qcGZS0OF7nfLzuYbjsQISwVO2HXrmf18gLWVX3Kwfw=
##
## Autumn configuration
##
# S3 Region
AUTUMN_S3_REGION=minio
# S3 Endpoint
AUTUMN_S3_ENDPOINT=http://minio:9000
# MinIO Root User
MINIO_ROOT_USER=minioautumn
# MinIO Root Password
MINIO_ROOT_PASSWORD=minioautumn
# AWS Access Key ID
AWS_ACCESS_KEY_ID=minioautumn
# AWS Secret Key
AWS_SECRET_ACCESS_KEY=minioautumn

Binary file not shown.

After

Width:  |  Height:  |  Size: 136 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 86 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 110 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 62 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 132 KiB

1
.gitignore vendored

@ -1,6 +1,7 @@
data*
.env
.env.web
Revolt.toml
compose.override.yml

@ -11,7 +11,7 @@
}
uri strip_prefix /ws
reverse_proxy @upgrade http://events:9000
reverse_proxy @upgrade http://events:14703
}
route /autumn* {
@ -21,7 +21,7 @@
route /january* {
uri strip_prefix /january
reverse_proxy http://january:7000
reverse_proxy http://january:14705
}
reverse_proxy http://web:5000

@ -19,57 +19,135 @@ This repository contains configurations and instructions that can be used for de
> 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 only available for `backend` and `bonfire` images currently, more to come.
> amd64 builds are not currently available for the web client.
## Quick Start
## Deployment
This repository provides reasonable defaults, so you can immediately get started with it on your local machine.
To get started, find yourself a suitable server to deploy onto, we recommend starting with at least 2 vCPUs and 2 GB of memory.
> [!WARNING]
> This is not fit for production usage; see below for the full guide.
> [!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! <br> 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.
![Select the location](.github/guide/hostinger-1.location.webp)
When asked, choose **Ubuntu Server** as your operating system, this is used by us in production and we recommend its use.
![Select the operating system](.github/guide/hostinger-2.os.webp)
If you've chosen to go with Hostinger, they include integrated malware scanning which may be of interest:
![Consider malware scanning](.github/guide/hostinger-3.malware.webp)
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:
![Configuration unfilled](.github/guide/hostinger-4.configuration.webp)
![Configuration filled](.github/guide/hostinger-5.configuration.webp)
Make sure to confirm everything is correct!
![Confirmation](.github/guide/hostinger-6.complete.webp)
Wait for your VPS to be created...
| ![Wait for creation](.github/guide/hostinger-7.wait.webp) | ![Wait for creation](.github/guide/hostinger-8.connect.webp) |
| --------------------------------------------------------- | ------------------------------------------------------------ |
After install, SSH into the machine:
```bash
git clone https://github.com/revoltchat/self-hosted revolt
cd revolt
cp .env.example .env
docker compose up
# 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
```
Now navigate to http://local.revolt.chat in your browser.
And now we can proceed with some basic configuration and securing the system:
## Production Setup
```bash
# 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
```
Prerequisites before continuing:
Your system is now ready to proceed with installation, but before we continue you should configure your domain.
- [Git](https://git-scm.com)
- [Docker](https://www.docker.com)
![Cloudflare DNS configuration](.github/guide/cloudflare-dns.webp)
Clone this repository.
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:
```bash
# 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:
```bash
git clone https://github.com/revoltchat/self-hosted revolt
cd revolt
```
Copy `.env` and download `Revolt.toml`, then modify them according to your requirements.
Generate a configuration file by running:
> [!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).
```bash
./generate_config.sh your.domain
```
You can find [more options here](https://github.com/revoltchat/backend/blob/df074260196f5ed246e6360d8e81ece84d8d9549/crates/core/config/Revolt.toml), some noteworthy configuration options:
- Email verification
- Captcha
- A custom S3 server
If you'd like to edit the configuration, just run:
```bash
cp .env.example .env
wget -O Revolt.toml https://raw.githubusercontent.com/revoltchat/backend/main/crates/core/config/Revolt.toml
micro Revolt.toml
```
Then start Revolt:
Finally, we can start up Revolt:
```bash
docker compose up
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.
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).
Pull the latest version of this repository:
@ -77,6 +155,8 @@ 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.
Then pull all the latest images:
```bash
@ -91,6 +171,37 @@ docker compose up
## Additional Notes
### Quick Start (for advanced users)
Prerequisites before continuing:
- [Git](https://git-scm.com)
- [Docker](https://www.docker.com)
Clone this repository.
```bash
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](#custom-domain).
```bash
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:
```bash
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:

@ -1,3 +1,5 @@
name: revolt
services:
# MongoDB database
database:
@ -15,16 +17,30 @@ services:
minio:
image: minio/minio
command: server /data
env_file: .env
volumes:
- ./data/minio:/data
environment:
MINIO_ROOT_USER: minioautumn
MINIO_ROOT_PASSWORD: minioautumn
MINIO_DOMAIN: minio
networks:
default:
aliases:
- revolt-uploads.minio
# legacy support:
- attachments.minio
- avatars.minio
- backgrounds.minio
- icons.minio
- banners.minio
- emojis.minio
restart: always
# Caddy web server
caddy:
image: caddy
restart: always
env_file: .env
env_file: .env.web
ports:
- "80:80"
- "443:443"
@ -35,24 +51,20 @@ services:
# API server (delta)
api:
image: ghcr.io/revoltchat/server:20240929-1
env_file: .env
image: ghcr.io/revoltchat/server:20241024-1
depends_on:
- database
- redis
- caddy
volumes:
- ./Revolt.toml:/Revolt.toml
restart: always
# Events service (quark)
events:
image: ghcr.io/revoltchat/bonfire:20240929-1
env_file: .env
image: ghcr.io/revoltchat/bonfire:20241024-1
depends_on:
- database
- redis
- caddy
volumes:
- ./Revolt.toml:/Revolt.toml
restart: always
@ -60,28 +72,24 @@ services:
# Web App (revite)
web:
image: ghcr.io/revoltchat/client:master
env_file: .env
depends_on:
- caddy
restart: always
env_file: .env.web
# File server (autumn)
autumn:
image: ghcr.io/revoltchat/autumn:1.1.11
env_file: .env
image: ghcr.io/revoltchat/autumn:20241024-1
depends_on:
- database
- createbuckets
- caddy
environment:
- AUTUMN_MONGO_URI=mongodb://database
volumes:
- ./Revolt.toml:/Revolt.toml
restart: always
# Metadata and image proxy (january)
january:
image: ghcr.io/revoltchat/january:0.3.5
depends_on:
- caddy
image: ghcr.io/revoltchat/january:20241024-1
volumes:
- ./Revolt.toml:/Revolt.toml
restart: always
# Create buckets for minio.
@ -89,16 +97,12 @@ services:
image: minio/mc
depends_on:
- minio
env_file: .env
entrypoint: >
/bin/sh -c "
/usr/bin/mc config host add minio http://minio:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD;
while ! /usr/bin/mc ready minio; do echo 'Waiting minio...' && sleep 1; done;
/usr/bin/mc mb minio/attachments;
/usr/bin/mc mb minio/avatars;
/usr/bin/mc mb minio/backgrounds;
/usr/bin/mc mb minio/icons;
/usr/bin/mc mb minio/banners;
/usr/bin/mc mb minio/emojis;
while ! /usr/bin/mc ready minio; do
/usr/bin/mc config host add minio http://minio:9000 minioautumn minioautumn;
echo 'Waiting minio...' && sleep 1;
done;
/usr/bin/mc mb minio/revolt-uploads;
exit 0;
"

@ -0,0 +1,26 @@
#!/usr/bin/env bash
# set hostname for Caddy
echo "HOSTNAME=https://$1" > .env.web
echo "REVOLT_PUBLIC_URL=https://$1/api" >> .env.web
# hostnames
echo "[hosts]" >> Revolt.toml
echo "app = \"https://$1\"" >> Revolt.toml
echo "api = \"https://$1/api\"" >> Revolt.toml
echo "events = \"wss://$1/ws\"" >> Revolt.toml
echo "autumn = \"https://$1/autumn\"" >> Revolt.toml
echo "january = \"https://$1/january\"" >> Revolt.toml
# VAPID keys
echo "" >> Revolt.toml
echo "[api.vapid]" >> Revolt.toml
openssl ecparam -name prime256v1 -genkey -noout -out vapid_private.pem
echo "private_key = \"$(base64 vapid_private.pem | tr -d '\n')\"" >> Revolt.toml
echo "public_key = \"$(openssl ec -in vapid_private.pem -outform DER|tail -c 65|base64|tr '/+' '_-'|tr -d '\n')\"" >> Revolt.toml
rm vapid_private.pem
# encryption key for files
echo "" >> Revolt.toml
echo "[files]" >> Revolt.toml
echo "encryption_key = \"$(openssl rand -base64 32)\"" >> Revolt.toml
Loading…
Cancel
Save