doc(prod): start documenting production stuff
Hopefully, we can get the community to start pooling knowledge of how to run go-ipfs in production.
Steven Allen committed
Jun 12, 2020 at 12:13 UTC
91de6c972e8c4ccd70af13836522f7fde219c1d8
1 file changed
+93
docs/production/reverse-proxy.md
new
+93
@@ -0,0 +1,93 @@
1
+# IPFS & Reverse HTTP Proxies
2
+
3
+When run in production environments, go-ipfs should generally be run behind a
4
+reverse HTTP proxy (usually NGINX). You may need a reverse proxy to:
5
+
6
+* Load balance requests across multiple go-ipfs daemons.
7
+* Cache responses.
8
+* Buffer requests, only releasing them to go-ipfs when complete. This can help
9
+ protect go-ipfs from the
10
+ [slowloris](https://en.wikipedia.org/wiki/Slowloris_(computer_security)
11
+ attack.
12
+* Block content.
13
+* Rate limit and timeout requests.
14
+* Apply QoS rules (e.g., prioritize traffic for certain important IPFS resources).
15
+* Expose a limited subset of the HTTP API.
16
+
17
+This document contains a collection of tips, tricks, and pitfalls when running a
18
+go-ipfs node behind a reverse HTTP proxy.
19
+
20
+## Peering
21
+
22
+Go-ipfs gateways behind a single load balancing reverse proxy should use the
23
+[peering](../config.md#peering) subsystem to peer with each other. That way, as
24
+long as one go-ipfs daemon has the content being requested, the others will be
25
+able to serve it.
26
+
27
+# Garbage Collection
28
+
29
+Gateways rarely store content permanently. However, running garbage collection
30
+can slow down a go-ipfs node significantly. If you've noticed this issue in
31
+production, consider "garbage collecting" by resetting the go-ipfs repo whenever
32
+you run out of space, instead of garbage collecting.
33
+
34
+1. Initialize your gateways repo to some known-good state (possibly pre-seeding
35
+ it with some content, a config, etc.).
36
+2. When you start running low on space, for each load-balanced go-ipfs node:
37
+ 1. Use the nginx API to set one of the upstream go-ipfs node's to "down".
38
+ 2. Wait a minute to let go-ipfs finish processing any in-progress requests
39
+ (or the short-lived ones, at least).
40
+ 3. Take the go-ipfs node down.
41
+ 4. Rollback the go-ipfs repo to the seed state.
42
+ 5. Restart the go-ipfs daemon.
43
+ 6. Update the nginx config, removing the "down" status from the node.
44
+
45
+This will effectively "garbage collect" without actually running the garbage
46
+collector.
47
+
48
+# Buffering Requests & Responses
49
+
50
+In general, requests to the gateway should be buffered by the reverse proxy for
51
+the best performance. This is usually enabled by default (`proxy_request_buffering`).
52
+
53
+## API
54
+
55
+The go-ipfs HTTP API (`/api/...`) starts sending a response before it's done
56
+reading the request. This allows it to, e.g., send back progress updates while
57
+adding a file to go-ipfs.
58
+
59
+However, these progress updates won't work if the HTTP reverse proxy is
60
+configured to buffer requests. While requests to the go-ipfs _gateway_ should
61
+usually be buffered for better performance, requests to the go-ipfs API should
62
+generally not be buffered.
63
+
64
+In NGINX, you can turn off buffering for the API with:
65
+
66
+```nginx
67
+server {
68
+ ...
69
+ location /api {
70
+ ...
71
+ proxy_request_buffering off;
72
+ proxy_buffering off;
73
+ proxy_http_version 1.1;
74
+ }
75
+}
76
+```
77
+
78
+See: https://github.com/ipfs/go-ipfs/issues/6402#issuecomment-643025868
79
+
80
+# Content Blocking
81
+
82
+TODO:
83
+
84
+* Filtering requests
85
+* Checking the X-IPFS-Path header in responses to filter again after resolving.
86
+
87
+# Subdomain Gateway
88
+
89
+TODO: Reverse proxies and the subdomain gateway.
90
+
91
+# Load balancing
92
+
93
+TODO: discuss load balancing based on the CID versus the source IP.