From 7c7ba6c6f45770bc470add4d9be8737e55eb217a Mon Sep 17 00:00:00 2001 From: Declan Chidlow <84255570+DeclanChidlow@users.noreply.github.com> Date: Tue, 9 Jan 2024 11:44:54 +0800 Subject: [PATCH] Improve README Improves formatting, fixes grammar and punctuation, and generally cleans up file. --- README.md | 78 +++++++++++++++++++++++++------------------------------ 1 file changed, 36 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 81b700e..65e414f 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,36 @@ # Before you get started -Please [read the FAQ before running your own server](https://developers.revolt.chat/faq/usage#guidelines-for-third-party-instances) and you may want to read about [additional notes relating to third-party instances](https://developers.revolt.chat/faq/instances). +Please [read the FAQ before running your own server](https://developers.revolt.chat/faq/usage#guidelines-for-third-party-instances). You may also want to read about our [additional notes relating to third-party instances](https://developers.revolt.chat/faq/instances). ## Errata Notice -- amd64 builds are only available for `backend` and `bonfire` images currently, more to come. -- ❗ **Important**: if you deployed Revolt before [2022-10-29](https://github.com/minio/docs/issues/624#issuecomment-1296608406), you may have to tag the `minio` image release if it's configured in "fs" mode. - ```yml - image: minio/minio:RELEASE.2022-10-24T18-35-07Z - ``` -- ❗ **Important**: if you deployed Revolt before [2023-04-21](https://github.com/revoltchat/backend/commit/32542a822e3de0fc8cc7b29af46c54a9284ee2de), you may have to flush your Redis database. - ```bash - # 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 - ``` +> [!NOTE] +> amd64 builds are only available for `backend` and `bonfire` images currently. More are planned in future. + +> [!IMPORTANT] +> If you deployed Revolt before [2022-10-29](https://github.com/minio/docs/issues/624#issuecomment-1296608406), you may have to tag the `minio` image release if it's configured in "fs" mode. +> ```yml +> image: minio/minio:RELEASE.2022-10-24T18-35-07Z +> ``` + +> [!IMPORTANT] +> If you deployed Revolt before [2023-04-21](https://github.com/revoltchat/backend/commit/32542a822e3de0fc8cc7b29af46c54a9284ee2de), you may have to flush your Redis database. +> ```bash +> # 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 +> ``` ## Quick Start -This repository provides reasonable defaults, so you can immediately get started with it on your local machine. +This repository provides reasonable defaults, allowing you to get started on your local machine with ease. -> **Warning** -> This is not recommended for production usage - see below for the full guide. +> [!WARNING] +> This is not recommended for production usage - see [below](#Setup) for the full guide. ```bash git clone https://github.com/revoltchat/self-hosted revolt @@ -34,7 +39,7 @@ cp .env.example .env docker-compose up -d ``` -Then simply go to http://local.revolt.chat +Then simply go to http://local.revolt.chat. # Setup @@ -44,24 +49,24 @@ Prerequisites before continuing: - [Docker Compose](https://docs.docker.com/compose/) - [Git](https://git-scm.com/) -Clone this repository. - +Clone this repository and open it: ```bash git clone https://github.com/revoltchat/self-hosted revolt cd revolt ``` -Copy the `.env` file and edit according to your needs. - -> **Warning**: The default configuration is intended for testing and only works on your local machine. If you want to deploy to a remote server, you need to edit the URLs in the `.env` file, please see the section below on [configuring a custom domain](#custom-domain). \ -> If you get a network error when trying to log in, **double check your configuration before opening an issue.** +> [!WARNING] +> The default configuration is intended for testing and only works on your local machine. If you want to deploy to a remote server, you need to edit the URLs in the `.env` file. Please see the section below on [configuring a custom domain](#custom-domain). \ +> If you get a network error when trying to log in, **double check your configuration prior to opening an issue.** +Copy the `.env` file: ```bash cp .env.example .env ``` -Then bring up Revolt: +Edit the `.env` file according to your requirements. +Then bring up Revolt: ```bash docker-compose up -d ``` @@ -71,19 +76,16 @@ docker-compose up -d Before updating Revolt, check the errata at the top for important information and check if there are any new required environment variables now present in the `.env` file. To update Revolt, first pull the latest copy of this repository to ensure you have the latest tags: - ```bash git pull ``` Then pull all the latest images: - ```bash docker-compose pull ``` Now you can restart your services: - ```bash docker-compose up -d ``` @@ -93,7 +95,6 @@ docker-compose up -d ### Custom domain To configure a custom domain, you should be able to do a search and replace on `local.revolt.chat` in the `.env` file, like so: - ```diff # .env - REVOLT_APP_URL=http://local.revolt.chat @@ -101,7 +102,6 @@ To configure a custom domain, you should be able to do a search and replace on ` ``` You will also want to change the protocols to enable HTTPS: - ```diff # .env - REVOLT_APP_URL=http://my.domain @@ -112,7 +112,6 @@ You will also want to change the protocols to enable HTTPS: ``` In the case of `HOSTNAME`, you must strip the protocol prefix: - ```diff # .env - HOSTNAME=https://my.domain @@ -122,7 +121,6 @@ In the case of `HOSTNAME`, you must strip the protocol prefix: ### Putting Revolt behind another reverse proxy (or on a non-standard port) Override the port definitions on `caddy`: - ```yml # docker-compose.yml services: @@ -131,11 +129,10 @@ services: - "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. +> [!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: - ```diff # .env - HOSTNAME=http://local.revolt.chat @@ -147,7 +144,6 @@ You can now reverse proxy to http://localhost:1234. ### Expose database You can insecurely expose the database by adding a port definition: - ```yml # docker-compose.override.yml services: @@ -158,8 +154,7 @@ services: ### 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 # docker-compose.override.yml services: @@ -169,10 +164,9 @@ services: ### Making your instance invite-only -Enable invite-only mode by setting `REVOLT_INVITE_ONLY` in `.env` to `1` +Enable invite-only mode by setting `REVOLT_INVITE_ONLY` in `.env` to `1`. Create an invite: - ```bash # drop into mongo shell docker-compose exec database mongosh