add some basic gateway documentation
License: MIT Signed-off-by: Steven Allen <steven@stebalien.com>
Steven Allen committed
Aug 20, 2018 at 15:53 UTC
1af6717eff4d121ac877f18441c334d608e85824
1 file changed
+48
docs/gateway.md
new
+48
@@ -0,0 +1,48 @@
1
+# Gateway
2
+
3
+An IPFS Gateway acts as a bridge between traditional web browsers and IPFS.
4
+Through the gateway, users can browse files and websites stored in IPFS as if
5
+they were stored in a traditional web server.
6
+
7
+By default, go-ipfs nodes run a gateway at `http://127.0.0.1:5001/`.
8
+
9
+We also provide a public gateway at `https://ipfs.io`. If you've ever seen a
10
+link in the form `https://ipfs.io/ipfs/Qm...`, that's being served from *our*
11
+gateway.
12
+
13
+## Configuration
14
+
15
+The gateway's configuration options are (briefly) described in the
16
+[config](https://github.com/ipfs/go-ipfs/blob/master/docs/config.md#gateway)
17
+documentation.
18
+
19
+## Directories
20
+
21
+For convenience, the gateway (mostly) acts like a normal web-server when serving
22
+a directory:
23
+
24
+1. If the directory contains an `index.html` file:
25
+ 1. If the path does not end in a `/`, append a `/` and redirect. This helps
26
+ avoid serving duplicate content from different paths.<sup>†</sup>
27
+ 2. Otherwise, serve the `index.html` file.
28
+2. Dynamically build and serve a listing of the contents of the directory.
29
+
30
+<sub><sup>†</sup>This redirect is skipped if the query string contains a
31
+`go-get=1` parameter. See [PR#3964](https://github.com/ipfs/go-ipfs/pull/3963)
32
+for details</sub>
33
+
34
+## Filenames
35
+
36
+When downloading files, browsers will usually guess a file's filename by looking
37
+at the last component of the path. Unfortunately, when linking *directly* to a
38
+file (with no containing directory), the final component is just a CID
39
+(`Qm...`). This isn't exactly user-friendly.
40
+
41
+To work around this issue, you can add a `filename=some_filename` parameter to
42
+your query string to explicitly specify the filename. For example:
43
+
44
+> https://ipfs.io/ipfs/QmfM2r8seH2GiRaC4esTjeraXEachRt8ZsSeGaWTPLyMoG?filename=hello_world.txt
45
+
46
+## MIME-Types
47
+
48
+TODO