doc/Install.md: Troubleshooting: loadavg, filesystem ACL, big uploads

diff --git a/doc/Install.md b/doc/Install.md
index 47f4f9e7851011fd3b670c3db9e0dbf9c43a1599..61c102e98e6e267043518e9a1f4df77ab31d2e48 100644 (file)
--- a/doc/Install.md
+++ b/doc/Install.md
@@ -449,3 +449,58 @@ section:
        sql_mode = '';
 
 After that, restart mysql and try again.
+
+### Your worker never or rarely runs
+
+Friendica is coded to always play nice. It checks whether the host machine is idle enough and if it _seems_ to be overloaded, it intermittently refuses to process the worker queue.
+
+Such checks originate from the days of single-user single-core machines and involves thresholds that you should adjust based on the number of exclusive CPU cores you have. See this issue for more information:
+
+* https://github.com/friendica/friendica/issues/10131
+
+If you want to be neighborly and are using a shared web hosting PaaS provider, especially within the free tier, you need to set `maxloadavg` to say twice the maximum value of `/proc/loadavg` during peak hours.
+
+If you have the whole (virtual) machine for yourself such as in case of an IaaS VPS, you can set it to orders of magnitude higher than its commonly observed value, such as 1000.
+
+You should instead enact limits in your web server configuration based on the number of entry processes to cap the concurrent memory usage of your PHP processes.
+See `RLimitMEM`, `RLimitCPU`, `RLimitNPROC`, `StartServers`, `ServerLimit`, `MaxRequestsPerChild`, `pm.max_children`, `pm.start_servers` and related options in your server.
+
+### Error uploading even small image files
+
+You tried to upload an image up to 100kB and it failed.
+
+You may not have the ownership or file mode set correctly if you are using the file system storage backend.
+
+Change the backend to database. If this solves it, that that is was needs to be fixed.
+
+### Error uploading large files
+
+You may find `413 Request Entity Too Large` or `500 Internal Error` in the network inspector of the browser if the file is too large, for example if it is a video.
+
+First try to upload a very small file, up to 100kB. If that succeeds, you will need to increase limits at multiple places, including on any web proxy that you are using.
+
+In your PHP ini:
+
+* `upload_max_filesize`: defaults to 2MB
+* `post_max_size`: defaults to 8MB, must be greater than `upload_max_filesize`
+* `memory_limit`: defaults to 128MB, must be greater than `post_max_size`
+
+You should verify whether you changed them in the _right file_ by checking the web interface at the end of the overview on the `Admin` panel.
+
+For Apache2:
+
+* `LimitRequestBody`: defaults to unlimited
+* `SSLRenegBufferSize`: defaults to 128kB, only if your site uses TLS and perhaps only when using `SSLVerifyClient` or `SSLVerifyDepth`
+
+For nginx:
+
+* `client_max_body_size`: defaults to 1MB
+
+If you are using the database backend for storage, increase this in your SQL configuration:
+
+* `max_allowed_packet`: defaults to 32MB
+
+If you use the ModSecurity WAF:
+
+* `SecRequestBodyLimit`: defaults to 12MB
+* `SecRequestBodyNoFilesLimit`: defaults to 128kB, should not apply to Friendica