Stoat Self-Hosted: Docker Deployment Without the Native Clients

What Stoat Self-Hosted Actually Installs

This repository is not the Stoat application itself. It is a set of configurations and instructions for deploying a full instance: the back-end, the web front-end, a file server, and a metadata and image proxy. That distinction matters when you plan capacity and upgrades, because the repository you clone is a deployment wrapper around several services rather than a single binary you compile. The README describes the target audience indirectly through its prerequisites: a server with at least 2 vCPUs and 2 GB of memory, Ubuntu Server as the recommended operating system, and a domain you control. The instructions walk through a Hostinger VPS as the worked example, but the README says you should be able to adapt them to other platforms. If you already run Docker workloads and have a domain pointing at a host, you are the intended reader. If you were looking for a managed chat service, this is the wrong repository, since every step from firewall rules to DNS records is yours to perform.

The Deployment Path: Firewall, DNS, Then Docker

The order in the README is deliberate. You secure the server before anything else. The firewall block opens ssh, http, https, 7881/tcp and the UDP range 50000:50100, then sets the default policy to deny and enables ufw. Those non-standard ports are not incidental: 7881 and the UDP range are part of how the instance communicates, and the README's additional notes include a dedicated section explaining why they are absent from the Caddyfile. If you deploy behind another cloud provider or on physical hardware, the README states you must forward 80, 443, 7881 and 50000-50100/udp yourself. DNS comes next: your domain or subdomain should point to the server's IP through A and AAAA records, or CNAME to the provided hostname. Only after that does the guide install dependencies, starting with ca-certificates, curl, git and micro, followed by Docker from Docker's own Ubuntu repository using the keyring at /etc/apt/keyrings/docker.asc. The sequence is a checklist, and skipping the firewall or DNS step will produce a deployment that appears to start but cannot be reached.

Where the Documentation Gets Thin

The supplied README is truncated before the Configuration and Updating sections, so the exact environment variables, compose file names and update commands are not visible in the material available here. That is a real gap for anyone evaluating the project: the deployment prerequisites are documented in detail, but the configuration surface is not. What the README does signal is that configuration changes are expected. It points to a separate Guides file for common alterations such as using NGINX or setting the instance to invite only, and it includes notes on placing the instance behind another reverse proxy or another port, on insecurely exposing the database, and on MongoDB and KeyDB compatibility. Those notes imply the default stack includes a database and a key-value store with version constraints you may need to satisfy. Treat the missing configuration reference as something to read in full on the repository before you commit, not as something the deployment guide will hand you.

The Client Support Gap Is the Main Constraint

The README's most consequential note is blunt: currently, most official clients do not support self-hosted instances. The web client works well, and the README says that when you install it as a PWA the experience is close to a native app. That is the whole pitch for self-hosting today, and it should shape your decision more than any server specification. If your users live in a native desktop or mobile client, this deployment will not serve them, regardless of how clean your Docker setup is. The README directs readers to the Guides file for more on clients, which suggests the situation is documented rather than accidental. There is also a video caveat: the additional notes include a section on getting kicked from video-enabled instances when turning on video, which indicates that video behaviour on self-hosted instances has known failure modes. Neither point disqualifies the project, but both belong in your evaluation before you migrate a community onto it.

Licensing, Branding and the AGPL-3.0 Boundary

The repository is licensed AGPL-3.0. If you modify the software and let users interact with it over a network, the AGPL's source-availability condition is the part that distinguishes it from permissive licences, and it is worth reading the licence text rather than relying on a summary. Separately, the README points to a developer-site FAQ titled What can I do with Stoat and how do I self-host? for information about licensing and brand use. That second pointer matters because running the software and using the Stoat name are treated as different questions. The README does not resolve either question inside the deployment instructions, and this article cannot give legal advice. If you plan to run this for an organisation or under a product name, read both the LICENSE file and the developer FAQ before you expose the instance publicly.

Maintenance Is a Moving Target, Not a One-Time Install

Two notices in the README describe ongoing work. The first is a warning: if you are updating an instance from before February 28, 2026, consult the notices section at the bottom of the README. The second is a note that a list of security advisories is provided at the bottom. Together they tell you the project expects operators to track changes and read advisories, not just pull and restart. The README also has a dedicated Updating section, though its contents are beyond the truncated material here. The practical cost is operator attention: an instance that is never updated accumulates both the migration debt described in the notices and whatever the advisories cover. If nobody on your team will read those sections before each upgrade, the deployment will drift. That is a staffing question as much as a technical one, and the README does not pretend otherwise.

Alternatives and the Difference in Approach

The obvious comparison is a general-purpose chat platform you host yourself, such as Matrix with its homeserver and bridge ecosystem, or a team-oriented tool like Mattermost. The difference is architectural emphasis. Stoat Self-Hosted ships a defined set of components (back-end, web front-end, file server, metadata and image proxy) behind a Caddy configuration and a fixed port set, and the README treats the web client plus PWA as the supported path. A Matrix deployment instead centres on federation between independent homeservers and a client matrix, which means your users are not limited to one vendor's client and your instance can talk to others. Mattermost targets workplace messaging with its own client apps. Neither is a drop-in replacement, and this article is not claiming feature parity. The question to ask is whether you need a single self-contained instance with a web-first client, which is what this repository delivers, or whether client diversity and federation are requirements that this deployment does not address.

Who Should Deploy This, and What to Check First

Deploy this if you want a Stoat instance on infrastructure you control, your users are comfortable in a browser or an installed PWA, and you have someone who will read the security advisories and the notices section before each update. Do not deploy it if native client support is a hard requirement, since the README states most official clients do not support self-hosted instances, or if you cannot absorb the February 28, 2026 migration note for older instances. Before you begin, confirm three things: that your host can forward 80, 443, 7881/tcp and 50000-50100/udp (or that your provider already permits them), that your domain's A, AAAA or CNAME records resolve to the server, and that the Configuration section you will need is readable in full on the repository rather than truncated. The minimal server the README recommends is 2 vCPUs and 2 GB of memory, and it names Ubuntu Server as the operating system used in production.

Editorial conclusion

Adopt this if you want a web-first Stoat instance on your own hardware and you accept the README's warning that most official clients do not support self-hosted instances. Do not adopt it if your users expect native desktop or mobile clients, or if you cannot commit to tracking the security advisories and the February 28, 2026 migration notice. Before deploying, verify that ports 80, 443, 7881/tcp and 50000-50100/udp are forwardable on your host and that your domain's A, AAAA or CNAME records already resolve to the server.

Official sources

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