diff --git a/docs/developer_guide/running.rst b/docs/developer_guide/running.rst index 0650e5e..0e57ab2 100644 --- a/docs/developer_guide/running.rst +++ b/docs/developer_guide/running.rst @@ -82,8 +82,7 @@ The service should be started from the ``ssclj/jar`` module of $ cd SlipStreamServer/ssclj/jar -To run the service, export the required environment variables, start Clojure -REPL with boot and in the REPL run the commands listed below:: +Start Clojure REPL with boot and in the REPL run the commands listed below:: $ boot server-repl boot.user=> (require '[com.sixsq.slipstream.ssclj.app.server :as server :reload true]) @@ -97,23 +96,23 @@ The services will be started on port ``8201``. You can set it as needed, taking into account that it will be required later during the startup of the main SlipStream service. -It is assumed that an instance of Elasticsearch is running on ``localhost:9300``. -If this is not the case, export the following environment variables defining the -coordinates of Elasticsearch:: +It is assumed that an instance of `Elasticsearch `__ is +running on ``localhost:9300``. If this is not the case, export the following +environment variables defining the coordinates of Elasticsearch:: $ export ES_HOST= $ export ES_PORT= The service uses the configuration file defined by ``CONFIG_NAME`` environment variable. To be found by the service, the file should be on the service's -classpath. ``SlipStreamServer/ssclj/jar/boot.build`` (the project's configuration file) -sets the service configuration file name and extends the classpath to include -the default location containing the file. Typically, the file is named -``config-hsqldb-mem.edn`` and located in ``test-resources``:: +classpath. ``SlipStreamServer/ssclj/jar/boot.build`` (the project's +configuration file) sets the service configuration file name and extends the +classpath to include the default location containing the file. Typically, the +file is named ``config-hsqldb-mem.edn`` and located in ``test-resources``:: - (environ :env {:config-name "config-hsqldb-mem.edn" + (environ :env {:config-name "config-hsqldb-mem.edn" ... - (set-env! :source-paths #(set (concat % #{"test" "test-resources"}))) + (set-env! :source-paths #(set (concat % #{"test" "test-resources"}))) ... So, both the file name and its location can be modified in ``boot.build``. @@ -122,10 +121,13 @@ Apart from other configuration parameters the configuration file contains HSQLDB configuration definition. Typical content looks like:: {:auth-db { - :classname "org.hsqldb.jdbc.JDBCDriver" - :subprotocol "hsqldb" - :subname "mem://localhost:9012/devresources" - :make-pool? true}} + :classname "org.hsqldb.jdbc.JDBCDriver" + :subprotocol "hsqldb" + :subname "mem://localhost:9012/devresources" + :make-pool? true}} + +The ``config-hsqldb.edn`` is part of the source code and located under +``resources/`` subdirectory. The service's log file can be found under ``logs/ssclj-.log``. @@ -168,13 +170,13 @@ archive (war file). :: $ cd SlipStreamServer/war - $ mvn jetty:run-war + $ mvn jetty:run-war -Dpersistence.unit=hsqldb-schema -If the last command returns an error like -``JettyRunWarMojo : Unsupported major.minor version 51.0`` make sure you -have Java 8 installed. You can find the appropriate download from the -Java web site. You may also want to consult `this -article `__ +If the last command returns an error like ``JettyRunWarMojo : Unsupported +major.minor version 51.0`` make sure you have Java 8 installed. You can find +the appropriate download from the Java web site. You may also want to consult +`this article +`__ for setting up the environment. As you can see, we run SlipStream as a war behind Jetty. Now that the @@ -189,11 +191,12 @@ the server pointing to source static location as following: $ export ES_HOST=localhost $ export ES_PORT=9300 $ mvn jetty:run-war \ + -Dpersistence.unit=hsqldb-schema \ -Dstatic.content.location=file:../../SlipStreamUI/clj/src/slipstream/ui/views The server makes use of Elasticsearch as database backend, therefore, you see the need to set the host and port of Elasticsearch. -You can also change the main database backend connection using the +You can also change the main database backend connection updating the ``persistence.unit``. For example: :: @@ -236,6 +239,156 @@ that both ``jar`` and ``conf`` artifacts should be added. ${project.version} +Starting HTTP Server and Reverce Proxy +-------------------------------------- + +HTTP server and reverse proxy are required to serve SlipStream static content +and calls to API. Below this is done on an example of `Nginx +`__. As there are complementary SlipStream services +(SlipStream server, SSCLJ server) which run on different ports, and the +fact that SlipStream force the usage of secure cookies, all services should be +run behind an SSL encryption. We use following simplified configuration of +Nginx to fulfill this need. + +* Nginx installation + +Linux users should install it from the official `documentation +`__ page. + +Mac OS X users can simply run :: + + brew install nginx + +* Nginx configuration + +By default, the main Nginx configuration file is named ``nginx.conf`` and +placed in the directory ``/usr/local/nginx/conf``, ``/etc/nginx``, or +``/usr/local/etc/nginx``. + +It should contain the following :: + + worker_processes 1; + + events { + worker_connections 1024; + } + + + http { + include mime.types; + default_type application/octet-stream; + sendfile on; + keepalive_timeout 65; + include servers/*.conf; + } + + +You need to create configuration for upstream SlipStream services and SSL that will be located +in ``nginx/servers`` and ``nginx/ssl`` respectively :: + + $ mkdir {servers,ssl} + $ cat > servers/slipstream.conf< servers/slipstream-proxy.params<< EOF + + proxy_http_version 1.1; + + set $via "1.1 $host"; + if ($http_via) { + set $via "$http_via, $via"; + } + + proxy_set_header Via $via; + proxy_set_header Host $http_host; + proxy_set_header Connection ""; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + proxy_set_header slipstream-authn-info ""; + proxy_set_header slipstream-ssl-server-name $ssl_server_name; + + proxy_redirect off; + + $ cd ssl + openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout nginx.key -out nginx.crt + +At this stage, your Nginx configuration directory should look like:: + + ├── [...] + ├── nginx.conf + ├── servers + │   ├── slipstream-proxy.params + │   └── slipstream.conf + ├── ssl + │   ├── nginx.crt + │   └── nginx.key + + +* Optionally you may want to test your Nginx configuration:: + + sudo nginx -t + +* Finally launch Nginx:: + + sudo nginx + +TCP port 443 which you have configured in ``servers/slipstream.conf`` is the +standard TCP port that is used for websites which use SSL, therefore your +Slipstream is available at ``https://localhost`` + + You are now ready to :ref:`configure ` your new SlipStream server.