Quick installation guide

This page explains how to install your own reTHINK domain to be able to deliver your own Hyperties, Protostubs or Data Schemas. After following this tutorial, you will be able to run all Hyperties Demos from the catalogue available here.

Please note that this section is dedicated to an operational platform. Developers should use the toolkit.

Requirements

The reThink Framework platform uses three main core back-end services shown in the following picture and described hereafter.

All back-end services are available in Docker images and the preferred host is an Ubuntu 14.04.

It is recommended that the containers are deployed behind a reverse proxy for several reasons:

– default DNS is used to access different components of the platform, adding a prefix. The reverse proxy can easily manage different virtual hosts thus simplifying access to these services.

– All back-end services are using different ports, using a reverse proxy is useful to allow using classical ports

– It is recommended that the certificates are managed on the front reverse proxy.

Some tools/servers to install:

apache2

– or nginx instead of apache2

reverse proxy in case of on apache2

docker-compose

If you choose a default apache2 server, for each sub-domain you need to use a config file, where you config the reverse proxy, you can check here a config for registry component.

https free trusted certificates can be obtained on let’s encrypt.

You need to have DNS configured for your host domain and for three sub-domains: catalogue, registry and msg-node.

Installation process

We will first install the three back-end reTHINK Services, then the application from scratch. To illustrate our text, we will consider that the DNS of the domain is csp.rethink.com

Here is a view of the interfaces:

1- Deploy reTHINK back-end services with Docker Compose. Get the docker-compose file and execute:

docker-compose up -d

2- reverse-proxy configuration. Let’s assume we are using Apache.

2.1- configure your domain by editing /etc/apache2/sites-available/000-default.conf with your domain:

  
    <VirtualHost *:443>
          ServerName csp.rethink.com
           DocumentRoot /var/www/html/
    </VirtualHost>

Activate your domain:

  
sudo a2ensite 000-default`
  

and restart it:

 
sudo /etc/init.d/apache2 restart
 

2.1- configure the reverse-proxy for the Domain Registry. Take note of your Domain Registry Docker Container IP address, move to sites-available dir and create registry.conf file with it:

  
<VirtualHost *:443>
     ServerName 'registry.csp.rethink.com'
     ProxyPass / http://172.20.0.4:4567/
     ProxyPassReverse / http://172.20.0.4:4567/
</VirtualHost>
 

Activate the sub-domain and restart it:

sudo a2ensite registry
sudo /etc/init.d/apache2 restart

To test if installation is OK, open https://registry.csp.rethink.com/live. It should provide you the current status of the registry.

The urls of the domain users are encoded to be able to be sent to the domain registry. For apache reverse proxy users the directives AllowEncodedSlashes On AND ProxyPass with nocanon.

2.3- configure the reverse-proxy for the Message Node. Take note of your Message Node Docker Container IP address and create registry.conf file at sites-available dir with:

  
<VirtualHost *:443>
     ServerName 'msg-node.csp.rethink.com'
     ProxyPass / http://172.20.0.2:9090/
     ProxyPassReverse / http://172.20.0.2:9090/
</VirtualHost>
 

Activate the sub-domain and restart it:

  
sudo a2ensite msg-node
sudo /etc/init.d/apache2 restart
 

To test if installation is OK, open https://msg-node.csp.rethink.com/live to give a view of the current status of the Message Node.

2.4- configure the reverse-proxy for the Catalogue. Take note of your Catalogue Docker Container IP address and create catalogue.conf file at sites-available dir with:

  
<VirtualHost *:443>
     ServerName 'catalogue.csp.rethink.com'
     ProxyPass / http://172.20.0.8:5683/
     ProxyPassReverse / http://172.20.0.8:5683/
</VirtualHost>
 

Activate the sub-domain and restart it:

  
sudo a2ensite catalogue
sudo /etc/init.d/apache2 restart
 

To test if installation is OK, open https://catalogue.csp.rethink.com/ gives a view of the current status of the catalogue node. It also allow to see connected databases and components.

2.5- configure the reverse-proxy for the App Server Demos. Take note of your App Server Docker Container IP address and create demos.conf file at sites-available dir with:

  
<VirtualHost *:443>
     ServerName 'demos.csp.rethink.com'
     ProxyPass / http://172.20.0.10/
     ProxyPassReverse / http://172.20.0.10/
</VirtualHost>
 

Activate the sub-domain and restart it:

  
sudo a2ensite demos
sudo /etc/init.d/apache2 restart
 

To test if installation is OK, open https://demos.csp.rethink.com/ and it should open the demos home page.

  1. The Browser Runtime has to be uploaded from .well-known/runtime/ must contain the last version of the runtime. It has to be filled with these files (rethink.js, index.html, core.js, context-service.js, identities-gui.js, policies-gui.js)

4- If required, configure the different IdPs to give your domain access to it.

4.1- The google idpproxy provided is working with an account that authorizes authentication process on a test platform, which probably does not include the one under installation. This means that by default, it is not possible to use google. To be able to do this, you have to:

– edit the sourceCode.js of the google idpproxy, change the account and secret of the google account

– authorize on this account the use of google auth API (https://console.developers.google.com/apis/), with the authorized redirect URI https://csp.rethink.com.

Hello World Application Deployment

The Hello World is published in the repository dev-app, and its installation manual is provided there. It can be deployed simply behind an HTTP server.

When all of this is done you can try to connect on the index.html of the hello-app. First step, you should be able to load the runtime, then to load an hyperty, then to contact hyperties.

Integration with IMS

You should follow this guide to integrate your application with IMS.

Docker compose details

Domain Registry

Domain registry is installable with a docker image. As the Domain Registry is necessary to run the messaging node, it has to be running first. The default port of the domain registry is 4567. The default DNS for our domain registry will be: registry.csp.rethink.com.

service for docker-compose file

'domain-registry':
    image: 'rethink/registry-domain-server:latest'
    container_name: 'domain-registry'
    networks:
      rethink:
        ipv4_address: 172.18.0.4
    environment:
      - STORAGE_TYPE=RAM
      - EXPIRES=3600
    expose:
      - '4568'
      - '4567'

Messaging node

This is the core plateform. ReTHINK has provided four implementations but only one is necessary to be installed:

WARNING

  • vertx installation: the node.config.json contains a parameter that will be used during the docker run through an environment variable. The domain parameter must contain the DNS of the full platform (here csp.rethink.com), and it will be used then to build the DNS of the componants (msg-node.csp.rethink.com, registry.csp.rethink.com, etc…). The registry url must be filled here, but it is not sure if it can be tuned. To install you can use docker image
  • nodejs installation: the docker-compose must be configured. If you use the script “start.sh”, it will also build the domain registry. The url to provide in the “environment” section is the domain of the plateform (here csp.rethink.com).
  • no Matrix installation: after building the docker image, the simplest is to use the dockerStart.sh script. Be carefull to enter the good folder for the volume mapping, suppress the parameters –net=rethink -p 8001:8001 when used with a proxy. Note also that the default is exposed on HTTP on 8001. The MatrixProtoStub example is showing an URL of WebSocket with wss on 443, which is what the reverse proxy will provide.
  • multiple installations of msg-node-vertx on the same machine to serve different servers they can’t be installed on the same network (use for example 172.18.0.2 and 172.19.0.2)
service for docker-compose file

'msg-node-vertx':
    image: 'rethink/msg-node-vertx:master'
    container_name: 'msg-node-vertx'
    environment:
      - MSG_NODE_CONFIG=env
      - NODE_DOMAIN=csp.rethink.com
      - NODE_PORT=9090
      - NODE_REGISTRY_URL=http://172.18.0.4:4567
      - NODE_GLOBAL_REGISTRY_URL=http://130.149.22.133:5002
      - NODE_REGISTRY_RETRIES=2
      - NODE_REGISTRY_SSL=false
      - NODE_REGISTRY_OWN_CERTIFICATES=false
    networks:
      rethink:
        ipv4_address: 172.18.0.2
    expose:
      - '443'

Catalogue

The catalogue is made out of two main components. A broker, that is needed to access the different services, and one or more databases. You can use this database, that should be possible to use on a production mode. Documentation can be accessed here.
First of all, the broker has to be installed. A dockerhub image is available.

broker component for docker-compose file

'catalogue-broker':
    image: rethink/catalogue-broker
    container_name: 'catalogue-broker'
    networks:
      rethink:
        ipv4_address: 172.18.0.8
    hostname: 'catalogue.csp.rethink.com'
    command: [-host, 'catalogue.csp.rethink.com', -default, protocolstub/VertxProtoStub, -default, protocolstub/VertxProtoStubNode]

    expose:
      - '443'
      - '5683'
catalogue database component using local database

'catalogue-database-ptinovacao':
    build: "./catalogue-database"
    container_name: 'catalogue-database-ptinovacao'
    network_mode: "service:catalogue-broker"
    command: [-host, catalogue.csp.rethink.com]
    depends_on:
      - 'catalogue-broker'