add docs for custom load balancers (#26)

* add docs for custom load balancers

* reword awkward sentence

* add example url

docs/guides/load-balancing.md

@@ -0,0 +1,70 @@
+# Load Balancing
+
+## Standard Load Balancer
+
+Each Rack contains a built-in HTTP/HTTPS load balancer.
+
+For an app named `myapp` with a `convox.yml` like this:
+
+    services:
+      web:
+        port: 3000
+
+Convox will automatically set up HTTPS load balancing to this service when it is deployed.
+
+    $ convox services
+    SERVICE  DOMAIN                               PORTS
+    web      web.myapp.0a1b2c3d4e5f.convox.cloud  443:3000
+
+You can then access the `web` service of this application using `https://web.myapp.0a1b2c3d4e5f.convox.cloud`
+
+### SSL Termination
+
+Convox will automatically configure SSL for the external services of your app using a certificate from
+[Lets Encrypt](https://letsencrypt.org/).
+
+> Convox will redirect HTTP requests on port 80 to HTTPS on port 443 using an HTTP 301 redirect.
+
+### End-to-End Encryption
+
+In the example above, a connection to your application would be HTTPS between the user and the Rack's load
+balancer and then HTTP between the load balancer and the application.
+
+If you would like this connection to be encrypted all the way to your application you must configure your
+application to listen for HTTPS on its defined port and update your `convox.yml`:
+
+    services:
+      web:
+        port: https:3000
+
+> It is permissible to use a self-signed certificate between the Rack load balancer and your application.
+
+## Custom Load Balancers
+
+If your application needs to expose arbitrary TCP ports or more than one HTTP port, you can configure
+custom load balancers.
+
+For a `convox.yml` like this:
+
+    balancers:
+      other:
+        service: web
+        ports:
+          5000: 3000
+          5001: 3000
+    services:
+      web:
+        port: 3000
+
+Convox will configure a dedicated load balancer for each entry in the `balancers:` section.
+
+    $ convox balancers
+    BALANCER  SERVICE  ENDPOINT
+    other     web      1.2.3.4
+
+You could then access this application using the following URLs:
+
+* `http://1.2.3.4:5000`
+* `http://1.2.3.4:5001`
+
+> Note that Convox will not configure SSL termination for ports on a custom load balancer.

pkg/manifest/manifest_test.go

@@ -19,6 +19,11 @@ func TestManifestLoad(t *testing.T) {
 						Source:   3000,
 						Target:   1000,
 					},
+					manifest.BalancerPort{
+						Protocol: "TCP",
+						Source:   3001,
+						Target:   5000,
+					},
 				},
 				Service: "api",
 			},
@@ -236,6 +241,7 @@ func TestManifestLoad(t *testing.T) {
 		"balancers.main.ports.3000",
 		"balancers.main.ports.3000.port",
 		"balancers.main.ports.3000.protocol",
+		"balancers.main.ports.3001",
 		"balancers.main.service",
 		"environment",
 		"params",

pkg/manifest/testdata/full.yml

@@ -5,6 +5,7 @@ balancers:
       3000:
         protocol: TCP
         port: 1000
+      3001: 5000
 environment:
   - DEVELOPMENT=true
   - GLOBAL=true

pkg/manifest/yaml.go

@@ -53,6 +53,30 @@ func (v *BalancerPort) SetName(name string) error {
 	return nil
 }
 
+func (v *BalancerPort) UnmarshalYAML(unmarshal func(interface{}) error) error {
+	var w interface{}
+
+	if err := unmarshal(&w); err != nil {
+		return err
+	}
+
+	switch t := w.(type) {
+	case map[interface{}]interface{}:
+		type balancerPort BalancerPort
+		var bp balancerPort
+		if err := remarshal(w, &bp); err != nil {
+			return err
+		}
+		v.Protocol = bp.Protocol
+		v.Target = bp.Target
+	case int:
+		v.Protocol = "TCP"
+		v.Target = t
+	}
+
+	return nil
+}
+
 func (v *Environment) UnmarshalYAML(unmarshal func(interface{}) error) error {
 	var w interface{}