Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Connected to #114 #115

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Connected to #114 #115

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0a75340
Connected to #114
May 23, 2017
8c4a7ac
Connected to #114 : added some text about how to force the usage of h…
May 26, 2017
f426318
Update running.rst
0xbase12 May 29, 2017
ab4327f
updates: running ssclj and nginx.
konstan Jun 19, 2017
044d8ad
Merge branch 'master' into issue_#114-contributors-login-after-build
konstan Jun 19, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 175 additions & 22 deletions docs/developer_guide/running.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand All @@ -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 <https://www.elastic.co>`__ is
running on ``localhost:9300``. If this is not the case, export the following
environment variables defining the coordinates of Elasticsearch::

$ export ES_HOST=<es-host>
$ export ES_PORT=<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``.
Expand All @@ -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``.

Expand Down Expand Up @@ -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 <http://www.jayway.com/2013/03/08/configuring-maven-to-use-java-7-on-mac-os-x/>`__
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
<http://www.jayway.com/2013/03/08/configuring-maven-to-use-java-7-on-mac-os-x/>`__
for setting up the environment.

As you can see, we run SlipStream as a war behind Jetty. Now that the
Expand All @@ -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:

::
Expand Down Expand Up @@ -236,6 +239,156 @@ that both ``jar`` and ``conf`` artifacts should be added.
<version>${project.version}</version>
</dependency>

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
<https://www.nginx.com>`__. 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
<https://www.nginx.com/resources/wiki/start/topics/tutorials/install/>`__ 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<<EOF

upstream slipstream_servers {
server 127.0.0.1:8080;

keepalive 50;
}

upstream ssclj_servers {
server 127.0.0.1:8201;

keepalive 50;
}

ssl_session_cache shared:SSL:1m;
ssl_session_timeout 30m;
ssl_session_tickets on;
ssl_prefer_server_ciphers on;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ecdh_curve prime256v1;
ssl_ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES128-SHA:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4:!3DES:AES128-GCM-SHA256";
resolver 8.8.8.8 8.8.4.4;

server {
listen 443 ssl http2; # deferred reuseport;

ssl_certificate /usr/local/etc/nginx/ssl/nginx.crt;
ssl_certificate_key /usr/local/etc/nginx/ssl/nginx.key;

# Include SlipStream common configuration parameters
location / {
proxy_pass http://slipstream_servers;
include servers/slipstream-proxy.params;
}

location /auth {
proxy_pass http://ssclj_servers;
include servers/slipstream-proxy.params;
}

location /api {
proxy_pass http://ssclj_servers;
include servers/slipstream-proxy.params;
}

location /filter-rank {
proxy_pass http://prs_servers;
include servers/slipstream-proxy.params;
}

}
EOF

$ cat > 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 <dg-cfg>` your new SlipStream
server.

Expand Down