Stoat Self-Hosted: Running the Stoat Chat Stack on Your Own Docker Host

What stoatchat/self-hosted actually deploys

The repository is a deployment kit, not the chat application itself. Its README states it contains configurations and instructions for deploying a full instance of Stoat, and names the four pieces: the back end, the web front end, a file server, and a metadata and image proxy. The compose.yml file shows how those pieces are assembled from images: a MongoDB container for the database, a valkey/valkey:9-alpine container described in comments as the event message broker and KV store, a rabbitmq:4 container as the internal message broker, MinIO as S3-compatible object storage, Caddy as the web server, and an api service pulled from ghcr.io. The audience is anyone who wants a Stoat instance on hardware they control, rather than on stoat.chat. That is a narrow but concrete goal, and the repository is honest about the boundaries: a note in the README says most official clients do not support self-hosted instances, that the web client works well, and that the PWA experience is close to a native app.

How the Docker Compose stack fits together

Read compose.yml top to bottom and the data flow is visible. Caddy publishes ports 80 and 443, mounts the Caddyfile and a generated stoat.json, and is aliased to the value of STOAT_DOMAIN, so it is the only service that needs to face the internet. The api service and the web front end sit behind it. MongoDB stores persistent state in ./data/db. RabbitMQ carries internal messages between services and keeps its state in ./data/rabbit. MinIO holds uploads in ./data/minio and registers several network aliases, including revolt-uploads.minio and legacy aliases such as attachments.minio and avatars.minio, which tells you the project was renamed and old hostnames still resolve inside the network. The database and RabbitMQ both define healthchecks, so dependent services can wait for them. Two port ranges never appear in the Caddyfile by design, and the README explains why: 7881 and 50000-50100/udp are for the voice and video path, not HTTP. That split is the main architectural fact to understand before you debug anything.

Installing Stoat Self-Hosted on Ubuntu Server

The README walks through a Hostinger VPS as the example platform but says the steps adapt to others, and it recommends Ubuntu Server, which it says is used in production. The stated minimum is at least 2 vCPUs and 2 GB of memory. After you SSH in, the first block updates the system and configures the firewall. Note the two non-HTTP rules: 7881/tcp and 50000:50100/udp, which the README ties to voice and video. If you are on another provider or bare metal, the README says you must forward ports 80, 443, 7881 and 50000-50100/udp.

apt-get update && apt-get upgrade -y
ufw allow ssh
ufw allow http
ufw allow https
ufw allow 7881/tcp
ufw allow 50000:50100/udp
ufw default deny
ufw enable

Before deploying, point your domain or subdomain at the server with A and AAAA records, or a CNAME. Then install Git and the tools the guide uses:

apt-get update
apt-get install ca-certificates curl git micro

Docker is installed separately, and the README links to Docker's own instructions for platforms other than Ubuntu. The repository root contains the files you need next: compose.yml, generate_config.sh, secrets.env.example and Caddyfile. The example secrets file signals that configuration is generated rather than hand-written, and generate_config.sh is the script that produces it. The README's own sections for configuration and updating are where the exact invocation lives; the repository layout alone does not show the flags. Once the stack is up, your first real use is opening your domain in a browser, because that is the client the README says works well.

Where the documentation leaves you on your own

The README is unusually candid about one limitation: most official clients do not support self-hosted instances. That is not a footnote, it is the deciding constraint. If your users expect a native mobile app or a desktop client pointed at your domain, this repository does not give them one today. The browser and the installed PWA are the supported path. A second gap is operational. The README documents updating and has a notices section warning that instances from before February 28, 2026 need special attention, but there is no rollback procedure described, and no backup guidance for the ./data directories that hold MongoDB, RabbitMQ and MinIO state. A third is support scope: the README says the project's own testing environment sits on a KVM 2 instance and that the team is happy to assist with issues, which reads as best-effort help rather than a support contract. Finally, the README carries a list of security advisories. For a service that terminates TLS and accepts uploads, that list is the first thing to read after install, not the last.

Stoat Self-Hosted versus a general-purpose chat server

The obvious alternative for a self-hosted chat deployment is a general-purpose server such as Matrix Synapse, which is built around federation between independent homeservers and a protocol other clients implement. Stoat Self-Hosted takes the opposite approach: it deploys one instance of one product, with its own back end, web front end, file server and proxy wired together in a single Compose file. The practical difference is what you inherit. With a federated protocol you gain a client ecosystem and the option to talk to other servers, and you take on protocol complexity and a heavier operational surface. With this repository you get a stack that is already assembled and a Caddyfile that already knows which ports belong to HTTP and which belong to voice, but you are tied to Stoat's clients and to Stoat's release cadence. Neither is better in the abstract. If interoperability is the requirement, this is the wrong shape. If running one chat product well on one box is the requirement, the Compose file here is far less work than assembling equivalent services yourself.

Licence and the cost of keeping it updated

The repository is licensed AGPL-3.0, and the README does not stop there: it points readers to a page on developers.stoat.chat titled "What can I do with Stoat and how do I self-host?" for information about licensing and brand use. That pointer matters more than the licence badge, because it covers brand use as well as code, and because AGPL-3.0 has obligations that trigger when you let users interact with a modified version over a network. This article cannot tell you what your obligations are; read that page and the LICENSE file before you modify and expose anything. On maintenance, the last push to the default branch was on 2026-09-06, so the repository is not archived and has seen recent activity. The upgrade cost itself is modest in structure: versioned images in compose.yml, a configuration script, and an updating section in the README. The real cost is the migration warning for pre-February 28, 2026 instances and the fact that you own the data volumes.

Editorial conclusion

Adopt stoatchat/self-hosted if you want a Stoat instance you control and are willing to run Ubuntu Server with Docker, Caddy and the bundled database, Redis, RabbitMQ and MinIO containers, and to treat the browser as your client. Do not adopt it if you need official mobile or desktop clients today, since the README states most official clients do not support self-hosted instances, or if you only have 1 GB of memory, because the README recommends at least 2 vCPUs and 2 GB. Before exposing anything, verify the ports 80, 443, 7881 and 50000-50100/udp are open and forwarded, check the security advisories list at the bottom of the README for your version, and read the notices section if your instance predates February 28, 2026.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Project website
4. README
5. stoatchat/self-hosted on GitHub