From 5eebd20e4e3ba08578002e0779d3dce773365fa2 Mon Sep 17 00:00:00 2001 From: Jacob Schlecht Date: Sat, 20 Jun 2026 09:38:40 -0600 Subject: [PATCH] docs: Add a guides section to go into more detail about things (#285) Signed-off-by: Jacob Schlecht --- Guides.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 67 +----------------------- 2 files changed, 153 insertions(+), 65 deletions(-) create mode 100644 Guides.md diff --git a/Guides.md b/Guides.md new file mode 100644 index 0000000..edd11d1 --- /dev/null +++ b/Guides.md @@ -0,0 +1,151 @@ +
+

+ Stoat Self-Hosted + + [![Stars](https://img.shields.io/github/stars/stoatchat/self-hosted?style=flat-square&logoColor=white)](https://github.com/stoatchat/self-hosted/stargazers) + [![Forks](https://img.shields.io/github/forks/stoatchat/self-hosted?style=flat-square&logoColor=white)](https://github.com/stoatchat/self-hosted/network/members) + [![Pull Requests](https://img.shields.io/github/issues-pr/stoatchat/self-hosted?style=flat-square&logoColor=white)](https://github.com/stoatchat/self-hosted/pulls) + [![Issues](https://img.shields.io/github/issues/stoatchat/self-hosted?style=flat-square&logoColor=white)](https://github.com/stoatchat/self-hosted/issues) + [![Contributors](https://img.shields.io/github/contributors/stoatchat/self-hosted?style=flat-square&logoColor=white)](https://github.com/stoatchat/self-hosted/graphs/contributors) + [![License](https://img.shields.io/github/license/stoatchat/self-hosted?style=flat-square&logoColor=white)](https://github.com/stoatchat/self-hosted/blob/main/LICENSE) +

+Self-hosting Stoat Guides +
+
+ +Below are guides provided by the core team and by the community. Contributions to guides are welcome! + +## Table of Contents + +- [Placing Stoat Behind Other Reverse Proxies](#placing-stoat-behind-other-reverse-proxies) + - [NGINX](#nginx) +- [Making Your Instance Invite-only](#making-your-instance-invite-only) + +## Placing Stoat Behind Other Reverse Proxies + +Stoat self host is configured to use a built-in Caddy proxy by default; however, it works with other reverse proxies as well. Below are guides on putting Stoat self host behind different reverse proxies. If there is a reverse proxy that you'd like to use that is not documented, feel free to open a PR for adding a guide for that reverse proxy here. + +>[!WARNING] +> It is strongly recommended if you do not know how to manage a reverse proxy already that you leave Stoat to be hosted by the built-in Caddy proxy. These guides are supplemental, and will not cover every step or every use case. + +>[!NOTE] +> If you plan on using a reverse proxy other than the built in proxy, you will need to enter `y` during the configuration process when it asks if you'd like to place Stoat behind another reverse proxy. This will expose the Caddy container on port 8880 by default and you can reverse proxy to . If you'd like to change what port the Caddy container listens on, you can change it in the `compose.overrides.yml` file. + +Assumptions made by these guides: +- The domain name for your Stoat self host is `your.domain` +- Your Caddy is configured to run on port 8880 + +### NGINX + +Configuring Stoat self host behind NGINX involves configuring the websocket routes. All other steps for configuring NGINX are the same as any other service. These instructions assume you are using an NGINX installed via apt on a Debian based server. Most of the instructions here should apply to a docker container install as well. Other configurations are left as an exercise for the reader. + +#### Install NGINX and Certbot + +```bash +sudo apt update && sudo apt install nginx certbot python3-certbot-nginx +``` + +#### Add a site file to sites-available + +Create a configuration file somewhere for Stoat and open it, you can do it at `/etc/nginx/sites-available`. + +```bash +sudo micro /etc/nginx/sites-available/your.domain +``` + +Configure your domain, below is a configuration that should work out of the box (after using certbot.) Ensure that websocket support is enabled for the `/ws` and `/livekit` routes. + +``` +server { + server_name your.domain; + + listen 80; + listen [::]80; + + location / { + proxy_pass http://localhost:8880; + proxy_set_header Host $server_name; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + location /ws { + proxy_pass http://localhost:8880; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $server_name; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + location /livekit { + allow all; + proxy_pass http://localhost:8880; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $server_name; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +#### Enable the site + +If you chose a different file name, make sure this reflects that. + +```bash +sudo ln -s /etc/nginx/sites-available/your.domain /etc/nginx/sites-enabled/your.domain +``` + +#### Test the new configuration + +```bash +sudo nginx -t +``` + +If there are any errors, address them. + +#### Restart NGINX + +```bash +sudo service nginx restart +``` + +#### Test that you can reach the service + +Open `http://your.domain` in your browser. You should land on the login page. Don't login yet, as you need to enable SSL. + +#### Run Certbot + +Certbot configuration is not covered by this guide. Please view Certbot documentation for nginx. After running Certbot, your domain should be set up to accept traffic on https and port 443. + +#### Test connection + +You should now be able to connect to `https://your.domain` in the browser and be able to use the site. To ensure proper configuration, test voice chat and notification support. + +## Making Your Instance Invite-only + +Add the following section to your `Revolt.toml` file: +```toml +[api.registration] +# Whether an invite should be required for registration +# See https://github.com/stoatchat/self-hosted#making-your-instance-invite-only +invite_only = true +``` + +Create an invite: + +```bash +# drop into mongo shell +docker compose exec database mongosh + +# create the invite +use revolt +db.invites.insertOne({ _id: "enter_an_invite_code_here" }) +``` \ No newline at end of file diff --git a/README.md b/README.md index ae01a8f..3716add 100644 --- a/README.md +++ b/README.md @@ -37,11 +37,11 @@ This repository contains configurations and instructions that can be used for de - [Insecurely Expose the Database](#insecurely-expose-the-database) - [Mongo Compatibility](#mongo-compatibility) - [KeyDB Compatibility](#keydb-compatibility) - - [Making Your Instance Invite-only](#making-your-instance-invite-only) - [Why ports 7881 and 50000-50100/udp aren't in the Caddyfile](#why-ports-7881-and-50000-50100udp-arent-in-the-caddyfile) - [Getting kicked on video enabled instances when turning on video](#getting-kicked-on-video-enabled-instances-when-turning-on-video) - [Notices](#notices) - [Security Advisories](#security-advisories) +- [Guides](Guides.md) ## Deployment @@ -223,49 +223,7 @@ docker compose up -d During configuration using `generate_config.sh` you will be asked if you'd like to place Stoat behind another reverse proxy. Enter `y` to configure for reverse proxy. This will expose your caddy on port 8880, and you can reverse proxy to -> [!NOTE] -> If you are using nginx as your reverse proxy, you will need to add the upgrade header configuration to allow websockets on /ws and /livekit, which are required for Stoat. -> Example: -> ``` -> server { -> server_name stoat.example.com; -> -> location / { -> allow all; -> proxy_pass http://localhost:1234; -> proxy_set_header Host $server_name; -> proxy_set_header X-Real-IP $remote_addr; -> proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; -> proxy_set_header X-Forwarded-Proto $scheme; -> } -> -> location /ws { -> allow all; -> proxy_pass http://localhost:1234; -> proxy_http_version 1.1; -> proxy_set_header Upgrade $http_upgrade; -> proxy_set_header Connection "upgrade"; -> proxy_set_header Host $server_name; -> proxy_set_header X-Real-IP $remote_addr; -> proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; -> proxy_set_header X-Forwarded-Proto $scheme; -> } -> -> location /livekit { -> allow all; -> proxy_pass http://localhost:1234; -> proxy_http_version 1.1; -> proxy_set_header Upgrade $http_upgrade; -> proxy_set_header Connection "upgrade"; -> proxy_set_header Host $server_name; -> proxy_set_header X-Real-IP $remote_addr; -> proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; -> proxy_set_header X-Forwarded-Proto $scheme; -> } -> . . . # The rest of your nginx configuration -> } -> ``` - +See [guides](Guides.md) for more information about placing Stoat behind other reverse proxies. ### Insecurely Expose the Database @@ -307,27 +265,6 @@ services: image: valkey/valkey:8 ``` -### Making Your Instance Invite-only - -Add the following section to your `Revolt.toml` file: -```toml -[api.registration] -# Whether an invite should be required for registration -# See https://github.com/stoatchat/self-hosted#making-your-instance-invite-only -invite_only = true -``` - -Create an invite: - -```bash -# drop into mongo shell -docker compose exec database mongosh - -# create the invite -use revolt -db.invites.insertOne({ _id: "enter_an_invite_code_here" }) -``` - ### Why ports 7881 and 50000-50100/udp aren't in the Caddyfile Livekit requires ports 7881/tcp and 50000-50100/udp to be openly accessible on the internet. These ports are used for the RTC protocol. Caddy does not support RTC without significant configuration changes that are out of scope of this repo.