Merge pull request #252 from vania-pooh/master

Better docs, disabling privileged mode and NPE fix

.travis.yml

@@ -8,7 +8,7 @@ services:
   - docker
 
 script:
-  - go test -race -coverprofile=coverage.txt -covermode=atomic -coverpkg .,github.com/aerokube/selenoid/session,github.com/aerokube/selenoid/config,github.com/aerokube/selenoid/protect
+  - go test -v -race -coverprofile=coverage.txt -covermode=atomic -coverpkg .,github.com/aerokube/selenoid/session,github.com/aerokube/selenoid/config,github.com/aerokube/selenoid/protect,github.com/aerokube/selenoid/service
   - GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -ldflags "-X main.buildStamp=`date -u '+%Y-%m-%d_%I:%M:%S%p'` -X main.gitRevision=`git describe --tags || git rev-parse HEAD`"
   - gox -os "linux darwin windows" -arch "amd64" -osarch="windows/386" -output "dist/{{.Dir}}_{{.OS}}_{{.Arch}}" -ldflags "-X main.buildStamp=`date -u '+%Y-%m-%d_%I:%M:%S%p'` -X main.gitRevision=`git describe --tags || git rev-parse HEAD`"
 

docs/browsers-configuration-file.adoc

@@ -1,6 +1,6 @@
 == Browsers Configuration File
 
-Selenoid uses simple JSON configuration files of the following format:
+Selenoid requires a simple JSON configuration file of the following format:
 
 .browsers.json
 [source,javascript]
@@ -44,6 +44,13 @@ Selenoid uses simple JSON configuration files of the following format:
 
 This file represents a mapping between a list of supported browser versions and Docker container images or driver binaries.
 
+[NOTE]
+====
+To use custom browsers configuration file - use `-conf` flag:
+
+    $ ./selenoid -conf /path/to/browsers.json
+====
+
 === Browser Name and Version
 Browser name and version are just strings that are matched against Selenium desired capabilities:
 
@@ -147,5 +154,5 @@ In some usage scenarios you may want to store browsers configuration file under
     # cat /path/to/browsers.json | jq -r '..|.image?|strings' | xargs -I{} docker pull {}
 
 NOTE: Why this is not the part of Selenoid? Well, this is easy to implement, but under heavy load the result can be unpredictable.
-For instance, you've updated file, reloaded Selenoid and it should pull new images. How long you should wait new sessions then?
-What if Docker Registry is inaccessible? So for maintenance reasons it is easier to delegate such simple logic to external script.
+For example after updating the file and reloading Selenoid it should pull new images. How long will you wait for new sessions then?
+What to do if Docker Registry is inaccessible? So for maintenance reasons it is easier to delegate such simple logic to external script.

docs/index.adoc

@@ -23,6 +23,7 @@ include::browser-images.adoc[leveloffset=+1]
 include::docker-settings.adoc[leveloffset=+1]
 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::reloading-configuration.adoc[leveloffset=+1]
 include::docker-compose.adoc[leveloffset=+1]

docs/logging-configuration-file.adoc

@@ -4,7 +4,7 @@ By default Docker container logs are saved to host machine hard drive. When usin
 But in big Selenium cluster you may want to send logs to some centralized storage like https://www.elastic.co/products/logstash[Logstash]
 or https://www.graylog.org/[Graylog].
 Docker provides such functionality by so-called https://docs.docker.com/engine/admin/logging/overview/[logging drivers].
-Selenoid logging configuration file allows to specify which logging driver to use globally for all started Docker
+An optional Selenoid logging configuration file allows to specify which logging driver to use globally for all started Docker
 containers with browsers. Configuration file has the following format:
 
 .config/container-logs.json
@@ -40,3 +40,10 @@ For example these Docker logging parameters:
     }
 }
 ----
+
+[NOTE]
+====
+To specify custom logging configuration file - use `-log-conf` flag:
+
+    $ ./selenoid -log-conf /path/to/logging.json ... 
+====

docs/updating-browsers.adoc

@@ -0,0 +1,46 @@
+== Updating Browsers
+
+One of the most frequent Selenoid maintenance tasks is updating browser versions. To modify the list of available browsers you need to:
+
+. Update browsers configuration file (aka `browsers.json`) by adding or deleting desired browser versions
+. When adding new browsers in containers - pull respective container images, e.g.:
+
+    $ docker pull selenoid/chrome:62.0
+
+. Restart Selenoid or hot reload its configuration. 
+
+
+=== The Short Way
+
+This approach is mainly convenient for **personal usage** because Selenoid is restarted i.e. any running browser sessions are interrupted. Just type one http://aerokube.com/cm/latest/[Configuration Manager] command:
+
+    $ ./cm selenoid update 
+
+This command will download latest Selenoid release, browser images, generate new `browsers.json` and restart Selenoid. You may want to add `--vnc` flag to download images with VNC support:
+
+    $ ./cm selenoid update --vnc
+
+Another useful flag is total number of last browser versions to download (default is `2`):
+
+    $ ./cm selenoid update --last-versions 5
+
+If you wish to pull new images and regenerate configuration without restarting Selenoid then type:
+
+    $ ./cm selenoid configure --vnc --last-versions 5
+
+=== A Bit Longer Way
+
+We recommend to use this approach on **production clusters** because Selenoid configuration is reloaded without restart.
+
+. Edit `browsers.json` file and pull new browsers containers manually or using <<Syncing Browser Images from Existing File>>. Alternatively configure Selenoid without restarting it like shown in previous section.  
+. Reload Selenoid configuration (see <<Reloading Configuration>> for more details):
+
+    $ docker kill -s HUP selenoid
+
+. To verify that configuration was reloaded you can check Selenoid health:
+
+    $ curl -s http://example.com:4444/ping
+    {"uptime":"<some-value>","lastReloadTime":"2017-05-12 12:33:06.322038542 +0300 MSK","numRequests":<some-number>}
+
++
+Here `lastReloadTime` field shows when browsers configuration was reloaded for the last time.

main.go

@@ -73,6 +73,7 @@ var (
 	confPath                 string
 	logConfPath              string
 	captureDriverLogs        bool
+	disablePrivileged        bool
 	conf                     *config.Config
 	queue                    *protect.Queue
 	manager                  service.Manager
@@ -105,6 +106,7 @@ func init() {
 	flag.Var(&cpu, "cpu", "Containers cpu limit as float e.g. 0.2 or 1.0")
 	flag.StringVar(&containerNetwork, "container-network", "default", "Network to be used for containers")
 	flag.BoolVar(&captureDriverLogs, "capture-driver-logs", false, "Whether to add driver process logs to Selenoid output")
+	flag.BoolVar(&disablePrivileged, "disable-privileged", false, "Whether to disable privileged container mode")
 	flag.Parse()
 
 	if version {
@@ -142,6 +144,7 @@ func init() {
 		Network:           containerNetwork,
 		StartupTimeout:    serviceStartupTimeout,
 		CaptureDriverLogs: captureDriverLogs,
+		Privileged:        !disablePrivileged,
 	}
 	if disableDocker {
 		manager = &service.DefaultManager{Environment: &environment, Config: conf}

service/docker.go

@@ -13,12 +13,16 @@ import (
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/network"
+	"github.com/docker/docker/api/types/strslice"
 	"github.com/docker/docker/client"
 	"github.com/docker/go-connections/nat"
 	"strings"
 )
 
-const comma = ","
+const (
+	comma    = ","
+	sysAdmin = "SYS_ADMIN"
+)
 
 // Docker - docker container manager
 type Docker struct {
@@ -54,13 +58,16 @@ func (d *Docker) StartWithCancel() (*StartedService, error) {
 		NetworkMode:  container.NetworkMode(d.Network),
 		Tmpfs:        d.Service.Tmpfs,
 		ShmSize:      getShmSize(d.Service),
-		Privileged:   true,
+		Privileged:   d.Privileged,
 		Resources: container.Resources{
 			Memory:   d.Memory,
 			NanoCPUs: d.CPU,
 		},
 		ExtraHosts: getExtraHosts(d.Service, d.Caps),
 	}
+	if !d.Privileged {
+		hostConfig.CapAdd = strslice.StrSlice{sysAdmin}
+	}
 	if d.ApplicationContainers != "" {
 		links := strings.Split(d.ApplicationContainers, comma)
 		hostConfig.Links = links
@@ -143,10 +150,12 @@ func getPortConfig(service *config.Browser, caps session.Caps, env Environment)
 }
 
 func getLogConfig(logConfig container.LogConfig, caps session.Caps) container.LogConfig {
-	const tag = "tag"
-	_, ok := logConfig.Config[tag]
-	if caps.Name != "" && !ok {
-		logConfig.Config[tag] = caps.Name
+	if logConfig.Config != nil {
+		const tag = "tag"
+		_, ok := logConfig.Config[tag]
+		if caps.Name != "" && !ok {
+			logConfig.Config[tag] = caps.Name
+		}
 	}
 	return logConfig
 }

service/service.go

@@ -22,6 +22,7 @@ type Environment struct {
 	Hostname          string
 	StartupTimeout    time.Duration
 	CaptureDriverLogs bool
+	Privileged        bool
 }
 
 // ServiceBase - stores fields required by all services