Merge pull request #501 from inoc603/docs

Update documentation for the new transparent proxy

FAQ.md

@@ -135,11 +135,9 @@ With updating the configuration, request `docker pull mysql:5.6` will be sent to
 
 > Note: please remember restarting container engine after updating configuration.
 
-## Can I set HTTP_PROXY to be dfdaemon address?
+## Can I set dfdaemon as HTTP_PROXY?
 
-Yes, HTTP_PROXY is used to proxy every request from docker engine, including requests `docker login`, `docker pull` and `docker push`. Once it is configured, the influenced parts could be expanded much more widely. Dragonfly's feature is only taking effect on `docker pull`. Thus every `docker pull` request will be sent to dfdaemon, no matter it is an official image from docker hub or from a third-party registry. However, everyone should keep in mind one point that even if user wish to pull image `a.b.com/mysql:5.6` from registry `a.b.com`, dfdaemon will pull the image `mysql:5.6` from the configured registry address of dfdaemon, such as `c.d.com`. As a result, user pulled image `mysql:5.6` from `c.d.com` rather than `a.b.com`.
-
-In addition, with `HTTP_PROXY` enabled, Dragonfly only supports protocol scheme `HTTP`. `HTTPs` will never be supported then.
+Yes, please refer to the [proxy guide](./docs/user_guide/proxy.md).
 
 ## Do we support HA of supernode in Dragonfly
 

docs/user_guide/proxy.md

@@ -0,0 +1,85 @@
+# Use dfdaemon as an HTTP proxy
+
+Dfdaemon can be used as an HTTP proxy to speed up image pulling from any registry
+as well as general HTTP downloads.
+
+Please first ensure that you know how to install and run [supernode](install_server.md)
+and [dfdaemon](install_client.md).
+
+**HTTPS support is currently very limited. All HTTPS request will be tunneled
+directly, without dfget.**
+
+## Proxy rule configuration
+
+Proxy rules are configured in `/etc/dragonfly/dfdaemon.yml`. For performance
+reason, dfdaemon will handle a request with the the first matching rule.
+
+```yaml
+proxies:
+# proxy requests directly, without dfget
+- regx: no-proxy-reg
+  direct: true
+# proxy all http image layer download requests with dfget
+- regx: blob/sha256/.*
+# change http requests to some-registry to https, and proxy them with dfget
+- regx: some-registry/
+  use_https: true
+```
+
+## Download images
+
+Add the following content to `/etc/dragonfly/dfdaemon.yml`.
+
+```yaml
+proxies:
+# proxy all http image layer download requests with dfget
+- regx: blob/sha256/.*
+```
+
+Set HTTP_PROXY for docker daemon in `/etc/systemd/system/docker.service.d/http-proxy.conf`.
+`65002` is the default proxy port for dfdaemon. This can be configured with the
+`--proxyPort` cli parameter of dfdaemon.
+
+```
+[Service]
+Environment="HTTP_PROXY=http://127.0.0.1:65002"
+```
+
+Set your registry as insecure in `/etc/docker/daemon.json`
+
+```json
+{
+  "insecure-registries": [ "your.registry" ]
+}
+```
+
+Start dfdaemon and restart docker daemon.
+
+```
+systemctl restart docker
+```
+
+Pull an image to see if it works. For registries that are not configured
+insecure, you can still pull image from it, but dfdaemon will not be able to
+speed up your downloads with dfget.
+
+```
+docker pull nginx
+docker pull your.registry/team/repo:tag
+```
+
+Then you can [check if your image is downloaded with dfget](../../FAQ.md#how-to-check-if-block-piece-is-distributed-among-dfgets-nodes).
+
+## Download files
+
+You can simply use `HTTP_PROXY` environment variable to let dfdaemon download
+requests that match the proxy rules. This works for any program that
+respects the `HTTP_PROXY` environment variable.
+
+```
+HTTP_PROXY=http://127.0.0.1:65002 curl http://github.com
+```
+
+HTTPS requests and requests that are not matched, will be proxied directly,
+and dragonfly is not able to speed up them.
+