Nekoproxyマニュアル草案

nekoproxy-how-to

# Nekoproxy ドキュメント化前の覚書

## 機能
- リバースプロキシ
- etcdによるLive-Configuration
  - `routes`を`etcd`に
- domain/url based routing
- TLS support
- マルチテナント
  - 複数の独立したセッション・認証系
- SNS Single Sign On
  - Twitter OAuth
- Docker ambassador pattern (Dynamic container linkage)

```
                            +---------+
                            | Twitter |
                            +-------- +
                                 ^
                                 |
                                auth
                                 |
                                 |
+---------+                +-----------+                           +------+ 
| Browser | -- request --> | Nekoproxy |  -- get routes/addr -->   | etcd |
+---------+                +-----------+                           +------+
                                 |                                    ^
                                 |                                    |
                               proxy                                addr
                                 |                                    |
                                 v                                    |
                           +-------------+                   +------------------+
                           | Application | <-- watch addr -- | nekoetcd-connect |
                           +-------------+                   +------------------+
```

## Build
```
$ git clone https://github.com/ukatama/nekoproxy.git
$ docker build -t ukatama/nekoproxy nekoproxy
$ git clone https://github.com/ukatama/nekoetcd-connect.git
$ docker build -t ukatama/nekoetcd-connect nekoetcd-connect
```

## Run
```
$ docker run -d --name redis redis
$ docker run -d --name mysql -e MYSQL_ROOT_PASSWORD=<PASSWORD> mysql
$ docker run -d --name etcd quay.io/coreos/etcd  \
    --listen-client-urls=http://0.0.0.0:2379,http://0.0.0.0:4001 \
    --advertise-client-urls=http://0.0.0.0:2379,http://0.0.0.0:4001
$ docker run -d --name nekoproxy \
    -p 80:80 -p 443:443 \
    --link redis:reddis --link mysql:mysql --link etcd:etcd \
    -v /path/to/config.json/usr/src/app/local.json:ro \
    -v /path/to/cert.pem:/etc/certs/cert.pem:ro \
    -v /path/to/privkey.pem:/etc/certs/privkey.pem:ro \
    --env NODE_ENV=production
    ukatama/nekoproxy
```

## Configuration

| key       | type            | value                                          |
|-----------|-----------------|------------------------------------------------|
| apps      | object          | See below                                      |
| etcd      | object          | etcd configuration                             |
| etcd.host | string          | etcd host address                              |
| etcd.port | number          | etcd port                                      |
| routes    | array or "etcd" | See below                                      |
| metrics   | object          | Pormetheus endpoint configuration (deprecated) |
| ssl.cert  | string          | Path to cert file                              |
| ssl.key   | string          | Path to private key file                       |


### apps
アプリケーションを記述。それぞれのアプリケーションで独立したセッションを持つ。
`apps.<APP>`にオブジェクトとして記述。<APP>はそのアプリケーションの識別子。

- `domain`と`session.cookie.domain`は基本的に同じ値
- `session.cookie.domain`と`session.secret`はプロキシ先の全てのアプリケーションと統一

| key                   | type   | value                            |
|-----------------------|--------|----------------------------------|
| name                  | string | App full name                    |
| domain                | string | Domain name                      |
| database              | object | SQL database configuration (Knex.js) |
| passport.twitter      | object | Twitter consumer key/secret      |
| redis                 | object | Redis configuration (node-redis) |
| signUp                | boolean | Enable sign up. trueで誰でも登録 |
| session               | object | Session configuration            |
| session.cookie.domain | string | Domain of cookie                 |
| session.store         | string | "redis" or "knex" (SQL DB)       |
| session.secret        | string | Secret value of session          |
| sslRedirect           | boolean | Redirect http to https          |

## Routes
Routeを記述するオブジェクトの配列。
etcdの/routesキーに登録するか、設定ファイルのroutesキーの下に記述
上から順にテストされ、hostとurlがマッチしたらプロキシ。マッチしなければ次のRouteに


etcdのキー/routesにroutes.jsonの内容を設定。
```bash
$ docker exec -i etcd /etcdctl set /routes "$(cat /path/to/routes.json)"
```

| key    | type    | descrption |
|--------|---------|------------------------|
| host   | string  | Hostヘッダの値にマッチ |
| url    | string  | URL (e.g. /foo/bar) にマッチ。正規表現。optional |
| app    | string  | アプリケーションの識別子。appsのそれ             |
| etcd   | string  | etcdにおける接続情報のキー。後述                 |
| public | boolean | trueにすると認証を無効化 |

e.g.

```json
[
  {
      "host": "chat.nekometer.info",
      "app": "nekorpg",
      "etcd": "nekochat"
  },
  {
      "host": "board.nekometer.info",
      "app": "nekorpg",
      "etcd": "nekoboard"
  },
  {
      "host": "chat.xxx",
      "app": "beniimo",
      "etcd": "beniimo-chat"
  },
  {
      "host": "dodontof.nekometer.info",
      "app": "nekorpg",
      "etcd": "nekorpg-dodontof",
      "public": true
  },
  {
      "host": "nekobuilder.xxx.xxx.jp",
      "app": "beniimo",
      "etcd": "nekobuilder",
      "url": "^/hook",
      "public": true
  },
  {
      "host": "nekobuilder.xxx.xxx.jp",
      "app": "beniimo",
      "etcd": "nekobuilder"
  }
  ...
]
```

## Connect
プロキシ先のアプリケーションと接続

e.g. nekochat

```bash
$ docker run -d --name nekochat <...options> nekochat # Target application
$ docker run -d --name nekochat-connect \
    --link etcd:etct \
    --link nekochat:nekochat \
    --env APP=nekochat \ # Routeのetcdに設定する値
    ukatama/nekoetcd-connect
```

nekoproxy.yml

apps:
  beniimo:
    name: BeniimoRPG
    domain: xxx.xxx.jp
    database:
      client: mysql2
      connection:
        host: mysql
        database: beniimo_trpg
        user: root
        password: <PASSWORD>
    passport:
      twitter:
        consumerKey: <CONSUMER_KEY>
        consumerSecret: <CONSUMER_SECRET>
    redis:
      host: redis
    signUp: false
    session:
      cookie:
        domain: xxx.xxx.jp
      store: redis
      secret: <SECRET FOR BeniimoRPG>
    sslRedirect: true
  nekorpg:
    name: NekoRPG
    domain: nekometer.info
    database:
      client: mysql2
      connection:
        host: nekorpg-mysql
        database: nekorpg
        user: root
        password: <PASSWORD>
    passport:
      twitter:
        consumerKey: <CONSUMER_KEY>
        consumerSecret: <CONSUMER_SECRET>
    session:
      cookie:
        domain: nekometer.info
      store: knex
      secret: <SECRET FOR NekoRPG>
    sslRedirect: true
etcd:
  host: etcd
routes: etcd
metrics:
  host: 0.0.0.0
  port: 8080
  path: /metrics
ssl:
  cert: /etc/certs/cert.pem
  key: /etc/certs/privkey.pem