docs: new installation 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

README.md

@@ -21,23 +21,10 @@ This repository contains configurations and instructions that can be used for de
 > [!NOTE]
 > amd64 builds are only available for `backend` and `bonfire` images currently, more to come.
 
-## Quick Start
+## Quick Start (for advanced users)
 
-This repository provides reasonable defaults, so you can immediately get started with it on your local machine.
+> [!IMPORTANT]
-
+> This guide is intended for system administrators that wish to know the bare minimum to deploy, please go to the [Deployment section](#deployment) for detailed instructions!
-> [!WARNING]
-> This is not fit for production usage; see below for the full guide.
-
-```bash
-git clone https://github.com/revoltchat/self-hosted revolt
-cd revolt
-cp .env.example .env
-docker compose up
-```
-
-Now navigate to http://local.revolt.chat in your browser.
-
-## Production Setup
 
 Prerequisites before continuing:
 
@@ -57,19 +44,122 @@ 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
 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
+```
+
+## 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.
+
+<!-- TODO: promo -->
+
+<!-- select location -->
+<!-- select ubuntu -->
+
+When asked, choose **Ubuntu Server** as your operating system, this is used by us in production and we recommend its use.
+
+<!-- anti virus upsell -->
+<!-- set secure root password (practice good security >64 chars) (OR disable password login, explained after) & RECOMMEND add ssh key (instructions provided by them) -->
+<!-- confirm everything is correct -->
+<!-- wait for setup! -->
+<!-- 7Aq4qTBMT1Gzt3K4J2oRzhzdqOn2wE5xvcu9ZpvxDeeO3tR32# -->
+
+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.
+
+<!-- screenshot -->
+
+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
+```
+
+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.
+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 +167,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

compose.yml

@@ -1,3 +1,5 @@
+name: revolt
+
 services:
   # MongoDB database
   database:
@@ -15,7 +17,6 @@ services:
   minio:
     image: minio/minio
     command: server /data
-    env_file: .env
     volumes:
       - ./data/minio:/data
     restart: always
@@ -24,7 +25,7 @@ services:
   caddy:
     image: caddy
     restart: always
-    env_file: .env
+    env_file: .env.web
     ports:
       - "80:80"
       - "443:443"
@@ -35,24 +36,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 +57,23 @@ services:
   # Web App (revite)
   web:
     image: ghcr.io/revoltchat/client:master
-    env_file: .env
-    depends_on:
-      - caddy
     restart: always
 
   # 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,7 +81,9 @@ services:
     image: minio/mc
     depends_on:
       - minio
-    env_file: .env
+    environment:
+      MINIO_ROOT_USER: minioautumn
+      MINIO_ROOT_PASSWORD: minioautumn
     entrypoint: >
       /bin/sh -c "
       /usr/bin/mc config host add minio http://minio:9000 $MINIO_ROOT_USER $MINIO_ROOT_PASSWORD;

generate_config.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+# hostnames
+echo "" >> Revolt.toml
+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)\"" >> Revolt.toml
+echo "public_key = \"$(openssl ec -in vapid_private.pem -outform DER|tail -c 65|base64|tr '/+' '_-'|tr -d '\n')\"" >> Revolt.toml
+
+# encryption key for files
+echo "" >> Revolt.toml
+echo "[files]" >> Revolt.toml
+echo "encryption_key = \"$(openssl rand -base64 32)\"" >> Revolt.toml