From 4be76b5f914c49cf2a4252a6d38ba459d86a76a2 Mon Sep 17 00:00:00 2001 From: Ivan Krutov Date: Thu, 11 May 2017 14:21:23 +0300 Subject: [PATCH] Moved development to adoc and shortened README.md --- README.md | 149 +---------------------------------------- docs/contributing.adoc | 50 ++++++++++++++ docs/index.adoc | 2 + 3 files changed, 54 insertions(+), 147 deletions(-) create mode 100644 docs/contributing.adoc diff --git a/README.md b/README.md index 0483dc6..b206f0b 100644 --- a/README.md +++ b/README.md @@ -46,151 +46,6 @@ $ cat /etc/grid-router/quota/test.xml http://test:test-password@localhost:4444/wd/hub ``` -## Configuration -Ggr is using two types of configuration files: -1) A single file to store user credentials - **users file**. -2) One **username.xml** file (**quota file**) for each user storing information about available browsers. +## Complete Guide & Build Instructions -### Creating Users File -Ggr is using [htpasswd](https://httpd.apache.org/docs/2.4/misc/password_encryptions.html) files to store authentication data. Passwords are stored in encrypted form. To create such file type: -1) Ensure you have ```htpasswd``` utility installed (e.g. from ```apache2-utils``` package on Ubuntu). -2) Create a new users file... -``` -$ htpasswd -bc /path/to/new.htpasswd username password -``` -... or update an existing one: -``` -$ htpasswd -b /path/to/existing.htpasswd username password -``` - -### Creating Quota Files -1) Quota files define available browsers for each user. All quota files should be placed to the same directory. -2) For user ```username``` quota file should be named ```username.xml```. -3) Each quota file contains the following XML: -``` - - - - - - - ... - - - ... - - - - ... - - - - ... - -... - -``` -Here we define a list of browser names, their versions and default version for each browser. Each version has one or more regions (in cloud term, i.e. data centers). Every region contains one or more hosts. Each host defined in XML should have Selenium listening on specified port. The XML namespace is needed to be fully compatible with [original](http://github.com/seleniumkit/gridrouter) Java GridRouter implementation. - -### Configuration File Locations -1) Default users file locations are: ```.htpasswd``` for standalone binary and ```/etc/grid-router/users.htpasswd``` for Docker image. -2) Default quota directory location is ```quota``` for standalone binary and ```/etc/grid-router/quota``` for Docker image. This is why just attaching ```/etc/grid-router``` to container as read-only volume is enough. -3) To specify custom configuration file locations pass additional arguments to Ggr: -``` -# ggr -quotaDir /path/to/quota/directory -users /path/to/.htpasswd # Standalone binary -# docker run -d --name ggr -v /etc/grid-router/:/etc/grid-router:ro --net host aerokube/ggr:1.1.1 -quotaDir /path/to/quota/directory -users /path/to/.htpasswd # Docker container -``` - -### Quota Reload and Graceful Restart -* To **reload quota files** just send **SIGHUP** to process or Docker container: -``` -# kill -HUP -# docker kill -s HUP -``` -* To **gracefully restart** (without losing connections) send **SIGUSR2**: -``` -# kill -USR2 -# docker kill -s USR2 -``` - -## How it Works -See the full history in our article - **Selenium testing: a new hope**: -* [Part 1](https://hackernoon.com/selenium-testing-a-new-hope-7fa87a501ee9) -* [Part 2](https://hackernoon.com/selenium-testing-a-new-hope-a00649cdb100) - -## Log Files -A typical log file looks like the following: -``` -2017/04/18 03:52:36 [12413389] [SESSION_ATTEMPTED] [my_quota] [192.168.2.3] [firefox-42.0] [firefox42-1.example.com:4444] [1] -2017/04/18 03:52:40 [12413389] [SESSION_FAILED] [my_quota] [192.168.2.3] [firefox-42.0] [firefox42-1.example.com:4444] Error forwarding the new session Request timed out waiting for a node to become available. -2017/04/18 03:52:40 [12413390] [SESSION_ATTEMPTED] [my_quota] [192.168.2.3] [firefox-42.0] [firefox42-5.example.com:4444] [2] -2017/04/18 03:52:45 [12413390] [5.86s] [SESSION_CREATED] [my_quota] [192.168.2.3] [firefox-42.0] [firefox42-5.example.com:4444] [0c500a6f-98d2-4871-acb7-637d85e1416a] [2] -.... -2017/04/18 03:53:05 [SESSION_DELETED] [192.168.2.3] [firefox42-5.example.com:4444] [0c500a6f-98d2-4871-acb7-637d85e1416a] -``` -Every line contains: - -| Field | Example | Notes | -| ----- | ------- | ----- | -| Time | 2017/04/18 03:52:36 | - | -| Request counter | [12413389] | Only present for new session requests. So far as session ID is unknown when doing attempts this counter is used to find all session attempts for each new session request. | -| Status | [SESSION_ATTEMPTED] | See table below for complete list of statuses. | -| Quota name | [my_quota] | Extracted from basic HTTP auth headers. | -| User IP | [192.168.2.3] | IPv4 or IPv6 address | -| Browser | [firefox-42.0] | Name and version. Only present for new session requests. | -| Hub host | [firefox42-1.example.com:4444] | Host from quota XML file | -| Attempt number | [1] | For SESSION_ATTEMPTED entries means current attempt number. For SESSION_CREATED entries means total number of attempts to create this session. | -| Session ID | [0c500a6f-98d2-4871-acb7-637d85e1416a] | As arrived from hub | -| Session start time | [5.86s] | - | -| Error | Error forwarding the new session Request timed out waiting for a node to become available. | Only present for SESSION_FAILED | - -The following statuses are available: - -| Status | Description | -| ------ | ----------- | -| BAD_JSON | User request does not contain valid Selenium data | -| BROWSER_NOT_SET | Browser name is not present or empty string | -| CLIENT_DISCONNECTED | User disconnected and doing session attempts was interrupted | -| INVALID_URL | Session ID does not contain information about host where it was created | -| ROUTE_NOT_FOUND | Trying to proxy session to unknown host. Usually means quota files inconsistency between multiple Ggr instances. | -| SESSION_ATTEMPTED | New user request for session arrived | -| SESSION_CREATED | A new session was created and returned to user | -| SESSION_DELETED | Existing session was deleted by user request | -| SESSION_FAILED | Session attempt on specified host failed | -| SESSION_NOT_CREATED | Attempts to create a new session on all hosts failed. An error was returned to user. | -| UNSUPPORTED_BROWSER | Requested browser name and version is not present in quota | - -## Development -To build Ggr: - -1) Install [Golang](https://golang.org/doc/install) -2) Setup `$GOPATH` [properly](https://github.com/golang/go/wiki/GOPATH) -3) Install [govendor](https://github.com/kardianos/govendor): -``` -$ go get -u github.com/kardianos/govendor -``` -4) Get Ggr source: -``` -$ go get -d github.com/aerokube/ggr -``` -5) Go to project directory: -``` -$ cd $GOPATH/src/github.com/aerokube/ggr -``` -6) Checkout dependencies: -``` -$ govendor sync -``` -7) Build source: -``` -$ go build -``` -8) Run Ggr: -``` -$ ./ggr --help -``` -9) To build [Docker](http://docker.com/) container type: -``` -$ GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -$ docker build -t ggr:latest . -``` +Complete reference guide (including build instructions) can be found at: http://aerokube.com/ggr/latest/ \ No newline at end of file diff --git a/docs/contributing.adoc b/docs/contributing.adoc new file mode 100644 index 0000000..55cbd64 --- /dev/null +++ b/docs/contributing.adoc @@ -0,0 +1,50 @@ +== Contributing & Development +To build Ggr: + +. Install https://golang.org/doc/install[Golang] +. Setup `$GOPATH` https://github.com/golang/go/wiki/GOPATH[properly] +. Install https://github.com/kardianos/govendor[govendor]: + + $ go get -u github.com/kardianos/govendor + +. Get Ggr source: + + $ go get -d github.com/aerokube/ggr + +. Go to project directory: + + $ cd $GOPATH/src/github.com/aerokube/ggr + +. Checkout dependencies: + + $ govendor sync + +. Build source: + + $ go build + +. Run Ggr: + + $ ./ggr --help + +[TIP] +==== +To build http://docker.com/[Docker] container type: + +[source,bash] +---- +$ GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build +$ docker build -t ggr:latest . +---- +==== + +=== Documentation + +Locally can be generated with: + +[source,bash] +---- +$ docker run --rm -v `pwd`/docs/:/documents/ \ + asciidoctor/docker-asciidoctor \ + asciidoctor -D /documents/output/ index.adoc +---- diff --git a/docs/index.adoc b/docs/index.adoc index 1b780cf..6698d21 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -25,3 +25,5 @@ include::quota-files.adoc[leveloffset=+1] include::quota-reload.adoc[leveloffset=+1] include::how-it-works.adoc[leveloffset=+1] include::log-files.adoc[leveloffset=+1] + +include::contributing.adoc[]