add main documentation
This commit is contained in:
parent
0f13d0d0fc
commit
b161246079
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
209
doc/README.md
209
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=<ssl cert key from above> --username=<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 [<flags>]
|
||||
|
||||
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
|
||||
<html><head><title>no backends connected</title></head><body><h1>no backends connected</h1><p>Please ensure a backend is running for wfall-hu-crow.routed.xeserv.us. This is request ID 01BVA69BJJKNSX05W4NS0PHECY.</p></body></html>
|
||||
```
|
||||
|
||||
#### Connect a backend
|
||||
|
||||
In another terminal window:
|
||||
```console
|
||||
$ route-cli test-server
|
||||
```
|
||||
|
||||
In yet another terminal window:
|
||||
```conosle
|
||||
$ route-httpagent -token=<token from above> -domain=<domain from above> -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
|
||||
12
mage.go
12
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")
|
||||
|
|
|
|||
Loading…
Reference in New Issue