stoatchat/self-hosted

This repository contains configurations and instructions that can be used for deploying a full instance of Stoat, including the back-end, web front-end, file server, and metadata and image proxy.

• Disclaimers and Information
• Deployment
  • Securing your server
  • Configuring your domain
  • Install Required Dependencies
• Configuration
• Updating
• Additional Notes
  • Placing Behind Another Reverse-Proxy or Another Port
  • Insecurely Expose the Database
  • Mongo Compatibility
  • KeyDB Compatibility
  • Why ports 7881 and 50000-50100/udp aren't in the Caddyfile
  • Getting kicked on video enabled instances when turning on video
• Notices
• Security Advisories
• Guides

To get started, find yourself a suitable server to deploy onto, we recommend starting with at least 2 vCPUs and 2 GB of memory.

The instructions going forward will use Hostinger as an example hosting platform, but you should be able to adapt these to other platforms as necessary. There are important details throughout.

When asked, choose Ubuntu Server as your operating system; this is used by us in production, and we recommend its use.

If you've chosen to go with Hostinger, they include integrated malware scanning, which may be of interest:

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:

Make sure to confirm everything is correct!

Wait for your VPS to be created...

After installation, SSH into the machine:

# 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

# update the system
apt-get update && apt-get upgrade -y

# configure firewall
ufw allow ssh
ufw allow http
ufw allow https
ufw allow 7881/tcp
ufw allow 50000:50100/udp
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.

Your domain (or a subdomain) should point to the server's IP (A and AAAA records) or CNAME to the hostname provided.

# ensure Git is installed
apt-get update
apt-get install ca-certificates curl git micro

# install docker
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 Stoat:

git clone https://github.com/stoatchat/self-hosted stoat
cd stoat

Generate a configuration file by running:

chmod +x ./generate_config.sh
./generate_config.sh your.domain

The generate_config.sh script will create the neccessary secrets required to create a Stoat instance, and the secrets will be inserted into a file named secrets.env. You should back up this file, as losing it may result in you losing access to all files on your Stoat instance.

You can find more options here, some noteworthy configuration options:

• Email verification
• Captcha
• A custom S3 server
• iOS & Android notifications (Requires Apple/Google developer accounts)

If you'd like to edit the configuration, just run:

micro Revolt.toml

Finally, we can start up Stoat. First, run it in the foreground with:

docker compose up

If it runs without any critical errors, you can stop it with Ctrl + C and run it detached (in the background) by appending -d.

docker compose up -d

Before updating, ensure you consult the notices at the top of this README, as well as the notices at the bottom, to check if there are any important changes to be aware of.

Pull the latest version of this repository:

git pull

Ensure that your secrets in Revolt.toml and secrets.env match. If your secrets don't match, copy the secrets from Revolt.toml to secrets.env. The following step will overwrite your existing configuration. If you have custom configuration settings you will need to copy them over afterwards. Alternatively, you can forgo running the configurator, but you may miss out on new features.

Run the configuration script with your domain and pass the overwrite flag:

./generate_config.sh --overwrite your.domain

Then pull all the latest images:

docker compose pull

Then restart the services:

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

See guides for more information about placing Stoat behind other reverse proxies.

You can insecurely expose the database by adding a port definition:

# compose.override.yml
services:
  database:
    ports:
      - "27017:27017"

Docker will bypass your ufw rules when you do this. This means that if the port is open, the database will be publically accessible and anyone will be able to modify it.

Older processors may not support the latest MongoDB version; you may pin to MongoDB 4.4 and update the healthcheck as such:

# compose.override.yml
services:
  database:
    image: mongo:4.4
    . . .
    healthcheck:
      test: echo 'db.runCommand("ping").ok' | mongo localhost:27017/test --quiet
      . . .

Some systems (including ARM systems) may not support the latest KeyDB version; you may use redis or valkey instead as such:

# compose.override.yml
services:
  redis:
    image: valkey/valkey:8

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.

Due to an incomplete implementation, Stoat will kick any user that attempts to stream a video that is larger than the maximum size defined in Revolt.toml. If you would like to increase the maximum size allowed on your Stoat instance, you can do so by modifying the video_resolution field under [features.limits.new_user] and [features.limits.default] to a larger value in your Revolt.toml. For example, 4k would be : [3996, 2160].

cp secrets.env.example secrets.env

micro secrets.env

sudo cp data/minio data/minio-bak

You can find information about security advisories on Stoat repositories on Github. Listed below are the latest versions that contain remediations, and links to the security advisory pages.

• backend - 0.15.0 - stoatchat/stoatchat
• for-web - 0.14.1 - stoatchat/for-web