Installation
============

Contact Synchronization server consists of two services: contact server and single sign on server. We provide preconfigured docker images for both services and a docker-compose file for simple deployment.

Requirements
------------

You will need a machine that runs a reasonably new version of docker engine (at least 1.10.0) and a reasonably new version of `docker-compose`_ (at least 1.6.0). Please refer to `docker installation guide`_ for your system on how to install docker and to `docker-compose installation guide`_ for information on how to install docker-compose.

.. _docker installation guide: https://docs.docker.com/engine/installation/
.. _docker-compose: https://docs.docker.com/compose/
.. _docker-compose installation guide: https://docs.docker.com/compose/install/

You will also need a TLS certificate for your contact server.

Installation
------------

Start by logging into our docker registry:

.. code-block:: bash

    docker login -u customer -p Aen1ieB5sh docker.acrobits.net

.. _key-generation:

Key generation
..............

Create a directory ``/etc/acrobits/sso/``

.. code-block:: bash

    mkdir -p /etc/acrobits/sso/

Create a private key inside this directory using the following command.  This key will be used by SSO to sign its responses.

.. code-block:: bash

    openssl genrsa | openssl pkcs8 -topk8 -inform PEM -nocrypt -out /etc/acrobits/sso/private-key.pem

Then create a directory ``/etc/acrobits/contact_server`` and place the corresponding public key into it, named ``public-key.pem`` using the following commands:

.. code-block:: bash

    mkdir -p /etc/acrobits/contact_server
    openssl rsa -in /etc/acrobits/sso/private-key.pem -pubout -out /etc/acrobits/contact_server/public-key.pem

You will also need to place the content of the file ``/etc/acrobits/contact_server/public-key.pem`` to the portal as *SSO JWT token public key*.

.. note::

    If you ever need to generate a new private key, you will also have to replace the public part in the portal and in the ``contact_server`` directory.

Starting the containers
.......................

Create an empty directory called ``contacts`` and inside it create a file called ``docker-compose.yml`` with the following content:

.. code-block:: yaml

  ---
  version: '2'
  networks:
    contactnetwork:
  services:
      sso:
        image: docker.acrobits.net/releases/sso
        ports:
          - "127.0.0.1:8082:8080"
        restart: always
        networks:
            contactnetwork:
        volumes:
            - /etc/acrobits/sso:/etc/acrobits/sso/:ro
  
      redis:
        image: redis:5
        restart: always
        networks:
            contactnetwork:
          
      mongo:
        image: mongo:3.6
        volumes:
          - /data/mongo:/data/db
        restart: always
        networks:
            contactnetwork:
        
      contact_server:
        image:  docker.acrobits.net/releases/contact_server
        ports:
          - "127.0.0.1:8081:8080"
        restart: always
        networks:
            contactnetwork:
        volumes:
            - /etc/acrobits/contact_server:/etc/acrobits/contact_server:ro



To start the services , run the following command in the directory:

.. code-block:: bash

    docker-compose up -d

This will pull all needed docker images from docker registries, start all relevant containers, link them together and make both sso and contact server listen on loopback interface on ports 8082 and 8081 respectively.

.. note::

   If you are deploying the services inside a virtual machine, the services may take a long time to start.
   This is because the machine does not have enough available entropy for random number generation.
   One way to increase available entropy is using `haveged`_ service.

.. _haveged: https://www.irisa.fr/caps/projects/hipsor/

The next step is setting up reverse HTTPS proxy that will expose both these services to your users. 

.. _sync-nginx-simple:

Suppose the machine running the services is example.com. Then you may want to expose sso server at https://example.com/sso and contact server at https://example.com/contacts. You can use the following snippet of nginx configuration as an inspiration.

.. code::

    server {
        listen 443 ssl;
        ssl_certificate /your/cert.pem;
        ssl_certificate_key /your/key.pem;
        server_name example.com;
        client_max_body_size 50m;

        location /contacts/ {
            proxy_pass http://localhost:8081/;
            error_log /var/log/nginx/contacts.error.log;
            access_log /var/log/nginx/contacts.access.log;
        }

        location /sso/ {
            error_log /var/log/nginx/sso.error.log;
            access_log /var/log/nginx/sso.access.log;
            proxy_pass http://localhost:8082/;
        }
    }

.. note::

   Nginx by default limits the size of body of POST requests to 1 MB which may not be enough in certain circumstances. We recommend setting it to 50 MB.