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

.env.example

@@ -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

.gitignore

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

Caddyfile

@@ -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

README.md

@@ -19,25 +19,159 @@ 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]
+> [!TIP]
-> This is not fit for production usage; see below for the full guide.
+>
+> **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
+# 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:
+
+```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
+```
+
+Your system is now ready to proceed with installation, but before we continue you should configure your domain.
+
+![Cloudflare DNS configuration](.github/guide/cloudflare-dns.webp)
+
+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
-cp .env.example .env
+```
+
+Generate a configuration file by running:
+
+```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
+micro Revolt.toml
+```
+
+Finally, we can start up Revolt:
+
+```bash
+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).
+
+Pull the latest version of this repository:
+
+```bash
+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
+docker compose pull
+```
+
+Then restart the services:
+
+```bash
 docker compose up
 ```
 
-Now navigate to http://local.revolt.chat in your browser.
+## Additional Notes
 
-## Production Setup
+### Quick Start (for advanced users)
 
 Prerequisites before continuing:
 
@@ -57,40 +191,17 @@ Copy `.env` and download `Revolt.toml`, then modify them according to your requi
 > 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
-cp .env.example .env
+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
+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.
-
-Pull the latest version of this repository:
-
-```bash
-git pull
-```
-
-Then pull all the latest images:
-
-```bash
-docker compose pull
-```
-
-Then restart the services:
-
-```bash
-docker compose up
-```
-
-## Additional Notes
-
 ### 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:

compose.yml

@@ -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
+    image: ghcr.io/revoltchat/server:20241024-1
-    env_file: .env
     depends_on:
       - database
       - redis
-      - caddy
     volumes:
       - ./Revolt.toml:/Revolt.toml
     restart: always
 
   # Events service (quark)
   events:
-    image: ghcr.io/revoltchat/bonfire:20240929-1
+    image: ghcr.io/revoltchat/bonfire:20241024-1
-    env_file: .env
     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
+    image: ghcr.io/revoltchat/autumn:20241024-1
-    env_file: .env
     depends_on:
       - database
       - createbuckets
-      - caddy
+    volumes:
-    environment:
+      - ./Revolt.toml:/Revolt.toml
-      - AUTUMN_MONGO_URI=mongodb://database
     restart: always
 
   # Metadata and image proxy (january)
   january:
-    image: ghcr.io/revoltchat/january:0.3.5
+    image: ghcr.io/revoltchat/january:20241024-1
-    depends_on:
+    volumes:
-      - caddy
+      - ./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
-      while ! /usr/bin/mc ready minio; do echo 'Waiting minio...' && sleep 1; done;
+        /usr/bin/mc config host add minio http://minio:9000 minioautumn minioautumn;
-      /usr/bin/mc mb minio/attachments;
+        echo 'Waiting minio...' && sleep 1;
-      /usr/bin/mc mb minio/avatars;
+      done;
-      /usr/bin/mc mb minio/backgrounds;
+      /usr/bin/mc mb minio/revolt-uploads;
-      /usr/bin/mc mb minio/icons;
-      /usr/bin/mc mb minio/banners;
-      /usr/bin/mc mb minio/emojis;
       exit 0;
       "

generate_config.sh

@@ -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