From 1af6717eff4d121ac877f18441c334d608e85824 Mon Sep 17 00:00:00 2001 From: Steven Allen Date: Mon, 20 Aug 2018 15:53:10 -0700 Subject: [PATCH] add some basic gateway documentation License: MIT Signed-off-by: Steven Allen --- docs/gateway.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/gateway.md diff --git a/docs/gateway.md b/docs/gateway.md new file mode 100644 index 00000000000..7f9326e5afa --- /dev/null +++ b/docs/gateway.md @@ -0,0 +1,48 @@ +# Gateway + +An IPFS Gateway acts as a bridge between traditional web browsers and IPFS. +Through the gateway, users can browse files and websites stored in IPFS as if +they were stored in a traditional web server. + +By default, go-ipfs nodes run a gateway at `http://127.0.0.1:5001/`. + +We also provide a public gateway at `https://ipfs.io`. If you've ever seen a +link in the form `https://ipfs.io/ipfs/Qm...`, that's being served from *our* +gateway. + +## Configuration + +The gateway's configuration options are (briefly) described in the +[config](https://github.com/ipfs/go-ipfs/blob/master/docs/config.md#gateway) +documentation. + +## Directories + +For convenience, the gateway (mostly) acts like a normal web-server when serving +a directory: + +1. If the directory contains an `index.html` file: + 1. If the path does not end in a `/`, append a `/` and redirect. This helps + avoid serving duplicate content from different paths.† + 2. Otherwise, serve the `index.html` file. +2. Dynamically build and serve a listing of the contents of the directory. + +†This redirect is skipped if the query string contains a +`go-get=1` parameter. See [PR#3964](https://github.com/ipfs/go-ipfs/pull/3963) +for details + +## Filenames + +When downloading files, browsers will usually guess a file's filename by looking +at the last component of the path. Unfortunately, when linking *directly* to a +file (with no containing directory), the final component is just a CID +(`Qm...`). This isn't exactly user-friendly. + +To work around this issue, you can add a `filename=some_filename` parameter to +your query string to explicitly specify the filename. For example: + +> https://ipfs.io/ipfs/QmfM2r8seH2GiRaC4esTjeraXEachRt8ZsSeGaWTPLyMoG?filename=hello_world.txt + +## MIME-Types + +TODO