Simon/self-hosted
1
0
Fork 0
mirror of https://github.com/stoatchat/self-hosted.git synced 2026-06-27 22:05:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add a guides section to go into more detail about things (#285)

Browse Source 
Signed-off-by: Jacob Schlecht <dadadah@echoha.us>
This commit is contained in:
Jacob Schlecht
2026-06-20 09:38:40 -06:00
committed by GitHub
parent 0f2b9f6662
commit 5eebd20e4e
2 changed files with 153 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

151
Guides.md Normal file
View File

@@ -0,0 +1,151 @@
<div align="center">
<h1>
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)
</h1>
Self-hosting Stoat Guides
</div>
<br/>
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 <http://localhost:8880>. 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" })
```

67
README.md
View File

@@ -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 <http://localhost:8880>
> [!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.