howto/gitlab: document some registry issues (team#41696)

howto/gitlab.md

@@ -960,6 +960,31 @@ storage:
 Another option that was explored while setting up the registry is
 enabling the [debug server](https://docs.gitlab.com/ee/administration/packages/container_registry.html#enable-the-registry-debug-server).
 
+#### HTTP 500 Internal Server Error
+
+If pushing an image to the registry fails with a HTTP 500 error, it's possible
+one of the image's layers is too large and exceeding the Nginx buffer. This can
+be confirmed by looking in `/var/log/gitlab/nginx/gitlab_registry_error.log`:
+
+```
+2024/08/07 14:10:58 [crit] 1014#1014: *47617170 pwritev() "/run/nginx/client_body_temp/0000090449" has written only 110540 of 131040, client: [REDACTED], server: containers.torproject.org, request: "PATCH /v2/lavamind/ci-test/torbrowser/blobs/uploads/df0ee99b-34cb-4cb7-81d7-232640881f8f?_state=HMvhiHqiYoFBC6mZ_cc9AnjSKkQKvAx6sZtKCPSGVZ97Ik5hbWUiOiJsYXZhbWluZC9jaS10ZXN0L3RvcmJyb3dzZXIiLCJVVUlEIjoiZGYwZWU5OWItMzRjYi00Y2I3LTgxZDctMjMyNjQwODgxZjhmIiwiT2Zmc2V0IjowLCJTdGFydGVkQXQiOiIyMDI0LTA4LTA3VDEzOjU5OjQ0Ljk2MTYzNjg5NVoifQ%3D%3D HTTP/1.1", host: "containers.torproject.org"
+
+```
+
+This happens because Nginx buffers such uploads under `/run`, which is a tmpfs
+with a default size of 10% of server's total memory. Possible solutions include
+increasing the size of the tmpfs, or disabling buffering (but this is untested
+and might not work).
+
+#### HTTP 502 Bad Gateway
+
+If such an error occurs when pushing an image that takes a long time (eg.
+because of a slow uplink) it's possible the authorization token lifetime limit
+is being exceeded.
+
+By default the token lifetime is 5 minutes. This setting can be changed via the
+GitLab admin web interface, in the Container registry configuration section.
+
 ## Disaster recovery
 
 In case the entire GitLab machine is destroyed, a new server should be