docker: add default nofile ulimits to docker-compose.yml

Add documentation section regarding OS limits and config

Resolves: #1020

CHANGELOG.md

@@ -9,6 +9,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ### Fixed
 - fix date-time format in `* /api/v1/markers` to strictly conform to Mastodon’s ISO 8061 subset
 
+### Changed
+- our Docker container now sets a default `nofile` `ulimit` to avoid issues on some systems.
+    Methods to customise this are documented under Configuration - General Optimisation.
+
 ## 2026.03.1
 
 ### Fixed

docker-compose.yml

@@ -45,6 +45,10 @@ services:
     ]
     volumes:
       - .:/opt/akkoma
+    ulimits:
+      # Maximum number of open file descriptors. The default should work well for most,
+      # but can be bumped for very large instances or if seeing FD-related errors.
+      nofile: 524288
 
   # Copy this into docker-compose.override.yml and uncomment there if you want to use a reverse proxy
   #proxy:

docs/docs/configuration/optimisation/general.md

@@ -46,3 +46,24 @@ might help alleviate the impact.
 
 If this condition does **not** hold though,
 setting up such a cache likely only worsens latency and wastes memory.
+
+# Ulimits
+
+Large instances may run into issues with too restrictive OS limits,
+such as `nofile` (the maximum number of open file descriptors).
+For `nofile` specifically, excessively large values can cause issues too however,
+since BEAM will allocate a port management structure whose size is based
+on this maximum leading to just as excessive RAM usage.
+
+On many distros the default limits per user can be configured in a file
+like `/etc/security/limits.conf` (see `man 5 limits.conf`) or an equivalent.
+Remember to change both soft and hard limits, such that the hard limit is
+always greater or equal to the soft limit.  
+You can always lower (but not raise) the limits dynamically for initial testing
+using e.g. `ulimit -Sn 65536 && /usr/bin/mix phx.server` *(this changes just the soft limit)*.
+
+Our Docker setup initialises the `nofile` limit to a reasonable default.
+If needed it can be changed via the `nofile` key in `ulimits` section
+of the `akkoma` service; either in `docker-compose.yml` directly,
+using the `docker-compose.override.yml` file or without recompiling the
+container image via `docker run --ulimit …`.