From b16124607935968556637339a736dc86cbf0447a Mon Sep 17 00:00:00 2001 From: Christine Dodrill Date: Sat, 30 Sep 2017 13:17:50 -0700 Subject: [PATCH] add main documentation --- README.md | 7 +- box.rb | 31 ++++++++ doc/README.md | 209 ++++++++++++++++++++++++++++++++++++++++++++++++++ mage.go | 12 +++ 4 files changed, 253 insertions(+), 6 deletions(-) create mode 100644 box.rb diff --git a/README.md b/README.md index 8db56d1..7e34251 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,5 @@ route ===== -A simple cluster-friendly load balancer for singleton microservices. +A simple cluster-friendly load balancer for http microservices. -TODO ----- - -- [ ] Store stuff into RethinkDB -- [ ] Add Let's Encrypt support in addition to a free tor hidden service with every domain routed diff --git a/box.rb b/box.rb new file mode 100644 index 0000000..7bce0ea --- /dev/null +++ b/box.rb @@ -0,0 +1,31 @@ +$goVer = "1.9" +$repoPath = "git.xeserv.us/xena/route" + +from "xena/go-mini:#{$goVer}" + +run "go download" + +[ + "vendor", + "internal", + "proto", + "cmd", + "lib", + "plugins", + "doc", +].each { |x| copy x+"/", "/root/go/src/#{$repoPath}/#{x}" } + +run "apk --no-cache add build-base" +run "go build -v #{$repoPath}/cmd/... && go install -v #{$repoPath}/cmd/..." +run "apk del build-base" + +[ + ["route", "route-cli"], + ["routed", "routed"], + ["route-httpagent", "route-httpagent"], +].each { |x| run "cp /root/go/bin/#{x[0]} /usr/local/bin/#{x[1]}" } + +run "apk del go1.9 && rm -rf /root/sdk /root/go" +flatten + +tag "xena/route:latest" diff --git a/doc/README.md b/doc/README.md index e69de29..992bf14 100644 --- a/doc/README.md +++ b/doc/README.md @@ -0,0 +1,209 @@ +Getting Started +=============== + +## Configuration + +```shell +# base configuration +BOLTDB_PATH=/routed/route.db +WEB_ADDR=:80 +SSL_ADDR=:443 +BACKEND_TCP_ADDR=:8757 +BACKEND_KCP_ADDR=:8804 +GRPC_ADDR=:7268 +DOMAIN_SUFFIX= +ACME_EMAIL= +SSL_CERT_KEY= +``` + +Fill out the missing parts of this and save it as `.env` somewhere. + +### `DOMAIN_SUFFIX` + +type: string + +When a domain is not supplied for a newly created route, domains will be a random +string prepended to this setting. Set up a wildcard DNS entry for this prefix pointed +to the server running routed. + +Example: `.route.xeserv.us` + +### `ACME_EMAIL` + +type: string, email address + +This email address will be used to establish an account with Let's Encrypt. By +using the ACME support route has you agree to follow all of the Let's Encrypt +terms and conditions [here][letoc]. + +### `SSL_CERT_KEY` + +type: string, encryption key + +This will be used to encrypt and decrypt all SSL certificates on the disk. +New keys can be generated by running `route generate-key`. + +## Node Setup + +The target node must have a direct route from the internet to TCP ports +`80`, `443`, `7268`, and `8757` and UDP port `8804`. In order they are used +for: + +| kind | port | usage | +|:-- |:-- |:-- | +| tcp | `80` | plain http traffic to backends | +| tcp | `443` | https (and http/2) traffic to backends | +| tcp | `7268` | grpc interface for management | +| tcp | `8757` | backend connections | +| udp | `8804` | backend connections | + +### Docker Volume Creation + +```console +$ docker volume create routed +``` + +### Initial Setup + +```console +$ docker run --rm -it -v routed:/routed xena/route:latest sh +(ctr)$ cd /routed +(ctr)$ route-cli token generate-root --key= --username= --db=./route.db +Your token is e73831bc-f40a-4cd4-84a6-b6b1e4529fa2 +(ctr)$ exit +``` + +Save this username and token as they will be very important. + +### Persistent setup with runit + +- Create a folder in `/etc/system` named `routed` + `# mkdir -p /etc/system/routed` +- Copy the `.env` file created above into `etc/system/routed` +- Create a file named `run` with the following contents: + +```sh +#!/bin/sh + +routeVer='latest' + +docker rm -f routed +sleep 2 +docker run --net host --name routed --rm -it --env-file .env -v routed:/routed -e BOLTDB_PATH=/routed/route.db xena/route:$routeVer +``` + +```console +# chmod +X /etc/system/routed/run +``` + +### Usage + +Change the definition of this variable as is needed for your setup. For now this must +be publicly facing but later versions of `route` will not require this. Set this in +a variable named `ROUTED_GRPC_ADDR`: + +```console +$ export ROUTED_GRPC_ADDR=h.routed.xeserv.us:7268 +``` + +Similarly, point this to the TCP backend connections port: + +```console +$ export ROUTED_TCP_BACKEND_ADDR=h.routed.xeserv.us:8757 +``` + +Next, open `~/.netrc` in your favorite editor and add the following to the end of it: + +``` +machine h.routed.xeserv.us:7268 + login usename + password token +``` + +#### Create a route + +``` +$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route create --help +‹master*!+1› »»»» ./route route create --help 0|12:57:46 +usage: route route create [] + +create a new route + +Flags: + --help Show context-sensitive help (also try + --help-long and --help-man). + --routed-addr="127.0.0.1:7268" + routed grpc address + --netrc="/Users/xena/.netrc" netrc path + --domain=DOMAIN domain for the route (if not given one will be + generated for you) + +$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route create +86d50f43-221d-4a57-99c9-8056dea0f12c +$ route-cli --routed-addr=$ROUTED_GRPC_ADDR route list ++--------------------------------------|--------------------------------+ +| ID | HOST | ++--------------------------------------|--------------------------------+ +| 86d50f43-221d-4a57-99c9-8056dea0f12c | wfall-hu-crow.routed.xeserv.us | ++--------------------------------------|--------------------------------+ +$ curl -v https://wfall-hu-crow.routed.xeserv.us +> GET / HTTP/2 +> Host: wfall-hu-crow.routed.xeserv.us +> User-Agent: curl/7.54.0 +> Accept: */* +> +* Connection state changed (MAX_CONCURRENT_STREAMS updated)! +< HTTP/2 502 +< accept: */* +< content-type: text/html; charset=utf-8 +< user-agent: curl/7.54.0 +< x-clacks-overhead: GNU Ashlynn +< x-forwarded-for: 24.17.183.23 +< x-remote-ip: 24.17.183.23 +< x-request-id: 01BVA69BJJKNSX05W4NS0PHECY +< x-request-ingress: 2017-09-30T22:05:21+02:00 +< content-length: 228 +< date: Sat, 30 Sep 2017 20:05:21 GMT +< +* Connection #0 to host wfall-hu-crow.routed.xeserv.us left intact +no backends connected

no backends connected

Please ensure a backend is running for wfall-hu-crow.routed.xeserv.us. This is request ID 01BVA69BJJKNSX05W4NS0PHECY.

+``` + +#### Connect a backend + +In another terminal window: +```console +$ route-cli test-server +``` + +In yet another terminal window: +```conosle +$ route-httpagent -token= -domain= -server=$ROUTED_TCP_BACKEND_ADDR +``` + +Now to your main terminal window: +```console +$ curl -v https://wfall-hu-crow.routed.xeserv.us +> GET / HTTP/2 +> Host: wfall-hu-crow.route.xeserv.us +> User-Agent: curl/7.54.0 +> Accept: */* +> +* Connection state changed (MAX_CONCURRENT_STREAMS updated)! +< HTTP/2 200 +< content-type: text/plain; charset=utf-8 +< date: Sat, 30 Sep 2017 20:15:59 GMT +< x-clacks-overhead: GNU Ashlynn +< x-request-id: 01BVA6WT90M20ZH6NVSKYT68SS +< content-length: 298 +< +Route is go! +map[X-Forwarded-For:[24.17.183.23, 193.164.132.229] X-Request-Id:[01BVA6WT90M20ZH6NVSKYT68SS] Accept-Encoding:[gzip] User-Agent:[curl/7.54.0] Accept:[*/*] X-Remote-Ip:[24.17.183.23] X-Request-Ingress:[2017-09-30T22:15:59+02:00]] +Served by cadance-3.local running darwin +* Connection #0 to host wfall-hu-crow.routed.xeserv.us left intact +Hit count: 1617 +``` + +--- + +[letoc]: https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf diff --git a/mage.go b/mage.go index 7ae4f75..597d0d1 100644 --- a/mage.go +++ b/mage.go @@ -107,6 +107,18 @@ func buildBins(goos string) { } } +// Docker builds docker images +func Docker() { + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + + ver, err := gitTag() + qod.ANE(err) + + shouldWork(ctx, nil, wd, "box", "box.rb") + shouldWork(ctx, nil, wd, "docker", "tag", "xena/route:"+ver) +} + // Linux builds binaries for linux func Linux() { buildBins("linux")