Explain what we know about Nginx chunked requests

diff --git a/lib/support/nginx/gitlab b/lib/support/nginx/gitlab
index c49dce5..5f517a1 100644 (file)
--- a/lib/support/nginx/gitlab
+++ b/lib/support/nginx/gitlab
@@ -1,6 +1,20 @@
 # GITLAB
 # Maintainer: @randx
 
+# CHUNKED TRANSFER
+# It is a known issue that Git-over-HTTP requires chunked transfer encoding [0] which is not
+# supported by Nginx < 1.3.9 [1]. As a result, pushing a large object with Git (i.e. a single large file)
+# can lead to a 411 error. In theory you can get around this by tweaking this configuration file and
+# - installing an old version of Nginx with the chunkin module [2] compiled in;
+# - using a newer version of Nginx.
+#
+# At the time of writing we do not know if either of these theoretical solutions works. As a workaround
+# users can use Git over SSH to push large files.
+#
+# [0] https://git.kernel.org/cgit/git/git.git/tree/Documentation/technical/http-protocol.txt#n99
+# [1] https://github.com/agentzh/chunkin-nginx-module#status
+# [2] https://github.com/agentzh/chunkin-nginx-module
+
 upstream gitlab {
   server unix:/home/git/gitlab/tmp/sockets/gitlab.socket;
 }