documentation and defaults improvements (#286)

documentation and defaults improvements * mention about cm start cmd, rm VOLUME from dockerfile * rm vnc mention
aerokube · Nov 27, 2017 · 53fcb51 · 53fcb51
1 parent a2eb107
commit 53fcb51
Show file tree

Hide file tree

Showing 10 changed files with 341 additions and 136 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -4,4 +4,6 @@ RUN apk add -U tzdata && rm -Rf /var/cache/apk/*
 COPY selenoid /usr/bin
 
 EXPOSE 4444
-ENTRYPOINT ["/usr/bin/selenoid", "-listen", ":4444", "-conf", "/etc/selenoid/browsers.json"]
+ENTRYPOINT ["/usr/bin/selenoid"]
+
+CMD ["-listen", ":4444", "-conf", "/etc/selenoid/browsers.json", "-video-output-dir", "/opt/selenoid/video/"]
diff --git a/docs/cli-flags.adoc b/docs/cli-flags.adoc
@@ -1,7 +1,8 @@
 == Selenoid CLI Flags
 
-The following flags are supported by ```selenoid``` command:
-```
+The following flags are supported by `selenoid` command:
+
+----
 -capture-driver-logs
     Whether to add driver process logs to Selenoid output
 -conf string
@@ -36,21 +37,23 @@ The following flags are supported by ```selenoid``` command:
     Session idle timeout in time.Duration format (default 1m0s)
 -version
     Show version and exit
-```
+-video-output-dir
+    Directory to save recorded video to (default "video")
+----
+
 For example:
 ```
-$ ./selenoid -conf /my/custom/browsers.json -limit 10
+$ ./selenoid -conf ~/.aerokube/selenoid/browsers.json -limit 10
 ```
 When using Selenoid inside Docker container these flags are passed like the following:
 
-
 [source,bash,subs="attributes+"]
 ----
 # docker run -d --name selenoid                     \
     -p 4444:4444                                    \
-    -v /etc/selenoid:/etc/selenoid:ro               \
+    -v ~/.aerokube/selenoid/:/etc/selenoid/:ro      \
     -v /var/run/docker.sock:/var/run/docker.sock    \
     aerokube/selenoid:latest-release                \
-    -conf /my/custom/browsers.json -limit 10
+    -conf /etc/selenoid/browsers.json -limit 10 -video-output-dir /opt/selenoid/video/
 ----
 
diff --git a/docs/index.adoc b/docs/index.adoc
@@ -17,6 +17,7 @@ It is using Docker to launch browsers. Please refer to https://github.com/aeroku
 
 == Getting Started
 include::quick-start-guide.adoc[leveloffset=+1]
+include::windows.adoc[leveloffset=+1]
 include::browser-images.adoc[leveloffset=+1]
 
 == Configuration
@@ -25,9 +26,9 @@ include::browsers-configuration-file.adoc[leveloffset=+1]
 include::logging-configuration-file.adoc[leveloffset=+1]
 include::updating-browsers.adoc[leveloffset=+1]
 include::timezone.adoc[leveloffset=+1]
+include::video.adoc[leveloffset=+1]
 include::reloading-configuration.adoc[leveloffset=+1]
 include::docker-compose.adoc[leveloffset=+1]
-include::windows.adoc[leveloffset=+1]
 include::log-files.adoc[leveloffset=+1]
 include::cli-flags.adoc[leveloffset=+1]
 

diff --git a/docs/quick-start-guide.adoc b/docs/quick-start-guide.adoc
@@ -1,55 +1,137 @@
 == Quick Start Guide
-. Download and run http://aerokube.com/cm/latest/[Configuration Manager] from https://github.com/aerokube/cm/releases/latest[releases] page.
-+
-**On Linux:**
 
-    $ curl -L -o cm https://github.com/aerokube/cm/releases/download/1.2.4/cm_linux_amd64
-    $ chmod +x ./cm
-    $ ./cm selenoid start --vnc
+[TIP]
+====
+The fastest way to start is http://aerokube.com/cm/latest/[Configuration Manager], which can be downloaded
+from https://github.com/aerokube/cm/releases/latest[releases] page. This tool will do all preparations automatically.
+Please refer to corresponding http://aerokube.com/cm/latest/[Quick Start with Configuration Manager] section.
 
-+
-**On Mac:**
+So all the content of this page can be simplified to only:
 
-    $ curl -L -o cm https://github.com/aerokube/cm/releases/download/1.2.4/cm_darwin_amd64
-    $ chmod +x ./cm
-    $ ./cm selenoid start --vnc
+----
+./cm selenoid start
+----
 
-+
-**On Windows** - just download the binary with your browser or if you have https://en.wikipedia.org/wiki/PowerShell[Powershell] type:
+This guide will show how to start Selenoid manually.
+====
 
-    > curl -L -o cm.exe https://github.com/aerokube/cm/releases/download/1.2.4/cm_windows_amd64
-    > ./cm.exe selenoid start --vnc
+WARNING: This Guide assumes you already know how to deal with command line and Docker in case of docker commands.
+Please take a look to CM first in any case.
 
-+
-[NOTE]
-====
-. If you have https://docs.docker.com/engine/installation/[Docker] installed you can also use this one-liner:
-[source,bash,subs="attributes+"]
-# docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v ${HOME}:/root -e OVERRIDE_HOME=${HOME} aerokube/cm:latest-release selenoid start --vnc --tmpfs 128
+=== Prepare
 
-. If you are working behind proxy you should set environment variables `HTTP_PROXY`, `HTTPS_PROXY` or `NO_PROXY` described in https://docs.docker.com/engine/admin/systemd/#runtime-directory-and-storage-driver[Docker documentation]:
-[source,bash,subs="attributes+"]
-$ HTTP_PROXY=http://proxy.example.com:80/ ./cm selenoid start
-+
-When running `cm` in container - pass variable via `-e` flag of the `docker` command. These variables work because `cm` is using the same client as `docker` command.
-====
+- Create `config/browsers.json` configuration file with content:
+
+.config/browsers.json
+[source,javascript]
+----
+{
+    "firefox": {
+        "default": "57.0",
+        "versions": {
+            "57.0": {
+                "image": "selenoid/vnc:firefox_57.0",
+                "port": "4444",
+                "path": "/wd/hub"
+            }
+        }
+    }
+}
+----
+
+- Pull browser docker image with `docker pull selenoid/vnc:firefox_57.0`.
 
-. Run your tests against Selenoid like you do with regular Selenium hub:
+=== Run binary
 
-    http://localhost:4444/wd/hub
+- Download binary for your operating system from https://github.com/aerokube/selenoid/releases/latest[releases] page
+and save it as `selenoid` (or `selenoid.exe` on windows).
 
-. Selenoid was created to be run in big Selenium clusters and thus has no built-in user interface. This is why trying to open an URL above in browser returns *404* and this is the expected behavior. If something does not work, you can easily check that Selenoid is running with `curl`:
+NOTE: Add execution permission in case of *nix os-type with `chmod +x selenoid`.
 
-    $ curl http://localhost:4444/status
+- Then run:
 
-+
-A successful request should return a JSON with browser usage statistics. 
-. You can additionally use http://github.com/aerokube/selenoid-ui[Selenoid UI] to see browser screen or consumption statistics. The simplest way is to download and run its binary from https://github.com/aerokube/selenoid-ui/releases[releases] page and start it:
+.*nix
+----
+./selenoid
+----
 
-    $ ./selenoid-ui
+.Windows
+----
+selenoid.exe
+----
 
-+
-See http://aerokube.com/selenoid-ui/latest/[UI documentation] for more installation options. By default UI is listening on port 8080. To start using it open the following page in your browser:
+It should write to console something like:
 
-    http://localhost:8080/
+----
+2017/11/26 21:23:43 Loading configuration files...
+2017/11/26 21:23:43 Loaded configuration from [config/browsers.json]
+
+...
+
+2017/11/26 21:23:43 Listening on :4444
+----
+
+=== Run selenoid with docker
+
+If you have https://docs.docker.com/engine/installation/[Docker] installed you can omit downloading binary and run it inside of container.
+Prepare config, pull browser image, then run:
+
+.*nix
+[source,bash,subs="attributes+"]
+----
+docker run -d                                   \
+--name selenoid                                 \
+-p 4444:4444                                    \
+-v /var/run/docker.sock:/var/run/docker.sock    \
+-v `pwd`/config/:/etc/selenoid/:ro              \
+aerokube/selenoid:latest-release
+----
+
+.Windows PowerShell
+[source,bash,subs="attributes+"]
+----
+> $current = $PWD -replace "\\", "/" -replace "C", "c"  <1>
+> docker run -d                                         `
+--name selenoid                                         `
+-p 4444:4444                                            `
+-v //var/run/docker.sock:/var/run/docker.sock           `
+-v ${current}/config/:/etc/selenoid/:ro                 `
+aerokube/selenoid:latest-release
+----
+<1> Simple macros to get $PWD with compatible form assumed your directory located on `C:` drive
+
+
+=== Use it for tests
+
+Run your tests against Selenoid like you do with regular Selenium hub:
+
+.Tests endpoint
+----
+http://localhost:4444/wd/hub
+----
+
+Selenoid was created to be run in big Selenium clusters and thus has no built-in user interface.
+This is why trying to open an URL above in browser returns *404* and this is the expected behavior.
+If something does not work, you can easily check that Selenoid is running with opening *status* url:
+
+.Current selenoid status
+----
+http://localhost:4444/status
+----
+
+A successful request should return a JSON with browser usage statistics.
+. You can additionally use http://github.com/aerokube/selenoid-ui[Selenoid UI] to see browser screen or consumption statistics.
+The simplest way is to download and run its binary from https://github.com/aerokube/selenoid-ui/releases[releases] page and start it:
+
+----
+./selenoid-ui
+----
+
+See http://aerokube.com/selenoid-ui/latest/[UI documentation] for more installation options.
+By default UI is listening on port 8080. To start using it open the following page in your browser:
+
+.UI default page with separate binary
+----
+http://localhost:8080/
+----
 
diff --git a/docs/reloading-configuration.adoc b/docs/reloading-configuration.adoc
@@ -18,7 +18,11 @@ $ curl -s http://example.com:4444/ping
 .Result
 [source,javascript]
 ----
-{"uptime":"2m46.854829503s","lastReloadTime":"2017-05-12 12:33:06.322038542 +0300 MSK","numRequests":42}
+{
+    "uptime": "2m46.854829503s",
+    "lastReloadTime": "2017-05-12 12:33:06.322038542 +0300 MSK",
+    "numRequests": 42
+}
 ----
 
-It returns `200 OK` when Selenoid operates normally. Additionally server uptime, last quota reload time and overall number of session requests from service startup are returned in JSON format.
+It returns `200 OK` when Selenoid operates normally. Additionally server uptime, last quota reload time and overall number of session requests from service startup are returned in JSON format.