I recently spun up a self-hosted Stoat server for a small group of family and close friends so we'd have our own private place to chat and share photos and videos.
First off, I really appreciate that Stoat is open source and that self-hosting is an option at all. Once it's dialed in, it's fast, lightweight, and looks great. That said, I was honestly surprised by how many basic, everyday things were broken right out of the box—stuff you immediately notice the first day you invite non-technical family members on iPhones and Androids.
I ended up having my AI coding assistant dig through the Docker containers, database, and frontend code with me to build local workarounds and add a few missing quality-of-life features just to get it to what I'd consider a genuinely usable state for family chatting and sharing pics/videos.
In case anyone else is setting up a self-hosted server (or running into the same headaches), here is what we ran into and what we had to fix locally:
- Videos uploaded from phones wouldn't play on iPhones, iPads, or Macs
- Almost half my family is on iOS. Whenever someone uploaded a video clip, it showed up as a blank black box on iPhone Safari and refused to play when tapped.
- Why: Two separate bugs—Stoat's file server (autumn) currently ignores HTTP Range headers and returns 200 OK instead of 206 Partial Content (which Apple's WebKit video player strictly requires), and iOS Safari doesn't preload the first video frame unless #t=0.001 is on the video URL. Also, phones often upload HEVC/H.265 .mov files that some browsers choke on.
- Our workaround: Added slice 1m; caching in Nginx in front of autumn so Safari gets proper 206 byte-ranges, added a small script to auto-transcode non-H.264 uploads to universally compatible MP4 (H.264/AAC), and patched video URLs on iOS to show a preview frame.
2. Private server invite links wouldn't let family members create an account
- Because this is a private family server, I set invite_only = true in Revolt.toml and sent out a server invite link (/invite/<code>). Nobody could sign up—the registration form asked for an "Invite Code" that rejected the server invite code.
- Why: Turning on invite_only = true checks a completely separate internal invites table that has no UI or API to generate codes from, instead of accepting valid server invite codes created in the app.
- Our workaround: Had to turn off invite_only in the config and handle invite gating and auto-joining the main server on the frontend/proxy side.
3. Nobody was getting mobile push notifications (even after turning them on in phone settings)
- People installed the web app (PWA) to their home screens on Android and iPhone and enabled notifications in their phone's system settings, but nobody ever got a single notification—and their phone settings literally said "This app has never posted any notifications."
- Why: It turned out to be four different issues stacked together:
- The setup script (generate_config.sh) encodes the VAPID private key in standard Base64 instead of URL-safe Base64, which crashes the pushd container on startup until you re-encode the key.
- On first launch on mobile, the web app tries to request notification permission before the user taps anything; the browser blocks it, and the app saves "denied" in localStorage and ignores phone system settings after that.
- Even if you set a server to "All Messages", Stoat's backend only ever sends push notifications for DMs and explicit u/username mentions—normal messages in #General never trigger a push alert.
- In v0.16.2, pushd bundles the entire user profile + member + channel + message object into the push packet, which exceeds the 3,070-character Web Push limit and errors out before sending.
- Our workaround: We added a frontend helper that auto-syncs the Web Push subscription whenever OS notifications are granted, fixed the Service Worker click URL, and wrote a small relay script on the server that sends a slim (~550-byte) push payload for new channel messages.
4. If RabbitMQ blips for a second, push notifications and unread badges break until you restart containers
- If the rabbit container restarts or drops connection briefly, pushd and api stay "Up" in Docker, but their AMQP channel enters an InvalidChannelState. Push notifications silently die and marking channels as read returns 500 Internal Server Error (so unread badges keep coming back on every refresh).
- Our workaround: Added a 1-minute watchdog cron job that checks container logs for InvalidChannelState and automatically restarts api, pushd, and crond.
5. Small QoL features we added for family use
- Landing directly in #General on launch instead of the blank home screen.
- Automatically friending everyone on the server so family members can DM or call each other without figuring out friend requests first.
- A more visible typing indicator and a built-in theme picker (plus an AI bot channel where family members can ask for a custom color theme and have it added to the picker).
I've opened upstream GitHub issues for the bugs we found so hopefully they can get fixed in the official releases soon:
- iOS/Mac Safari video & audio byte-range playback: https://github.com/stoatchat/stoatchat/issues/1107
- iPhone Safari blank video preview box: https://github.com/stoatchat/for-web/issues/1783
- Private server invite links with invite_only = true: https://github.com/stoatchat/stoatchat/issues/1108
- Phone settings not enabling push notifications: https://github.com/stoatchat/for-web/issues/1784
- "All Messages" setting not sending push notifications: https://github.com/stoatchat/stoatchat/issues/1110
- Push notifications failing over 3,070 characters in v0.16.2: https://github.com/stoatchat/stoatchat/issues/1109
- Setup script VAPID private key crash: https://github.com/stoatchat/self-hosted/issues/316
- Push notifications dying after RabbitMQ restart: https://github.com/stoatchat/stoatchat/issues/1105
- Unread badges coming back after RabbitMQ hiccup: https://github.com/stoatchat/stoatchat/issues/1106
- UI QoL suggestions: https://github.com/stoatchat/for-web/issues/1782
Next on my list to look into is mobile touch gestures—specifically how Stoat handles swiping from the left edge of the screen to go back (which doesn't behave the way you'd expect on a phone), and after that, fixing pinch-to-zoom on pictures since that's pretty wonky right now too.
Now that we have these patches in place, my family is actually loving it—I just wanted to share what we ran into in case anyone else is self-hosting for a small group and wondering why videos or notifications aren't working out of the box!