Improve documentation.

Fixes #46, #47

README.md

@@ -4,9 +4,19 @@ Let's Encrypt client and ACME library written in Go
 [![GoDoc](https://godoc.org/github.com/xenolf/lego/acme?status.svg)](https://godoc.org/github.com/xenolf/lego/acme)
 [![Build Status](https://travis-ci.org/xenolf/lego.svg?branch=master)](https://travis-ci.org/xenolf/lego)
 
-This is a work in progress. Please do *NOT* run this on a production server.
+#### General
+This is a work in progress. Please do *NOT* run this on a production server and please report any bugs you find!
 
-Please report any bugs you find!
+#### Installation
+lego supports both binary installs and install from source.
+
+To get the binary just download the latest release for your OS/Arch from [the release page](https://github.com/xenolf/lego/releases)
+and put the binary somewhere convenient. lego does not assume anything about the location you run it from.
+
+To install from source, just run 
+```
+go get -u github.com/xenolf/lego
+```
 
 #### Current Status
 The code in this repository is under development.
@@ -30,10 +40,22 @@ Please keep in mind that CLI switches and APIs are still subject to change.
 When using the standard --path option, all certificates and account configurations are saved to a folder *.lego* in the current working directory.
 
 #### Sudo
-I tried to not need sudo apart from challenges where binding to a privileged port is necessary.
+The CLI does not require root permissions but needs to bind to port 80 and 443 for certain challenges. 
 To run the CLI without sudo, you have two options:
-- Use ```setcap 'cap_net_bind_service=+ep' /path/to/program```
+
-- Pass the --port option and specify a custom port to bind to. In this case you have to forward port 443 to this custom port.
+- Use setcap 'cap_net_bind_service=+ep' /path/to/program
+- Pass the `--port` option and specify a custom port to bind to. In this case you have to forward port 443 to this custom port.
+
+#### Port Usage
+By default lego assumes it is able to bind to ports 80 and 443 to solve challenges.
+If this is not possible in your environment, you can use the `--port` option to instruct
+lego to listen on that port for any incoming challenges.
+
+If you are using this option, make sure you proxy all of the following traffic to that port:
+- All plaintext HTTP requests to port 80 which begin with a request path of `/.well-known/acme/` for the HTTP-01 challenge.
+- All TLS handshakes on port 443 for TLS-SNI-01.
+
+This traffic redirection is only needed as long as lego solves challenges. As soon as you have received your certificates you can deactivate the forwarding.
 
 #### Usage
 
@@ -68,6 +90,7 @@ GLOBAL OPTIONS:
 ##### CLI Example
 
 Assumes the `lego` binary has permission to bind to ports 80 and 443. You can get a pre-built binary from the [releases](https://github.com/xenolf/lego/releases) page.
+If your environment does not allow you to bind to these ports, please read [Port Usage](#port-usage).
 
 Obtain a certificate:
 
@@ -118,7 +141,8 @@ myUser := MyUser{
 // A client facilitates communication with the CA server. This CA URL is
 // configured for a local dev instance of Boulder running in Docker in a VM.
 // We specify an optPort of 5001 because we aren't running as root and can't
-// bind a listener to port 443 (used later when we attempt to pass challenge).
+// bind a listener to port 80 or 443 (used later when we attempt to pass challenges).
+// Keep in mind that we still need to proxy challenge traffic to port 5001.
 client, err := acme.NewClient("http://192.168.99.100:4000", &myUser, rsaKeySize, "5001")
 if err != nil {
   log.Fatal(err)

cli.go

@@ -83,7 +83,7 @@ func main() {
 		},
 		cli.StringFlag{
 			Name:  "port",
-			Usage: "Challenges will use this port to listen on. Please make sure to forward port 443 to this port on your machine. Otherwise use setcap on the binary",
+			Usage: "Challenges will use this port to listen on. Please make sure to forward port 80 and 443 to this port on your machine. Otherwise use setcap on the binary",
 		},
 	}