Advanced Installation
=====================

The method described in :doc:`the installation guide<installation>` will install fully functional contact synchronization server. The information in this file will describe the installation with configuration files and with one additional and optional component called Admin server. Admin server is a service based on Spring Boot Admin that provides some statistics and control over the server.

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

.. note::

    A lot of steps are similar to steps in :doc:`the simple installation guide<installation>`. We recommend reading it first. It may describe some steps in greater detail.

We start by creating some configuration files. Create the following files with the following content. Replace the passwords with secure ones that you generate:

File ``/etc/acrobits/admin-server/application.yml``:

.. code-block:: yaml

    ---
    spring.security.user.name: "admin"
    spring.security.user.password: "adminserverpassword"


File ``/etc/acrobits/sso/application.yml``:

.. code-block:: yaml

    ---
    adminServerEnabled: true
    spring.security.user.name: "admin"
    spring.security.user.password: "adminserverpassword"

File ``/etc/acrobits/contact_server/application.yml``:

.. code-block:: yaml

    ---
    adminServerEnabled: true
    spring.security.user.name: "admin"
    spring.security.user.password: "adminserverpassword"


Replace ``adminserverpassword`` in all three files with a secure password. This password will be used by you to log into Admin server.  It will also be used by other services to talk to the Admin server.

The next step is logging into our docker registry.

.. code-block:: bash

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

Next, generate a private and public key pair. The procedure is described in the basic installation guide under :ref:`Key generation for SSO<key-generation>`.

Create an empty directory named ``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
            volumes:
                - /etc/acrobits/sso:/etc/acrobits/sso:ro
            networks:
                contactnetwork:
    
    
        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:
                    aliases:
                        - contacts
            volumes:
                - /etc/acrobits/contact_server:/etc/acrobits/contact_server:ro
    
        admin-server:
            image: docker.acrobits.net/releases/admin-server
            ports:
                - "127.0.0.1:8004:8004"
            volumes:
                - /etc/acrobits/admin-server:/etc/acrobits/admin-server:ro
            restart: always
            networks:
                contactnetwork:

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

.. code-block:: bash

    docker-compose up -d

The next step is setting up reverse TLS proxy. The process is similar to the one described in :ref:`the regular installation guide<sync-nginx-simple>`. The difference is an additional ``location`` section.

Use the following snippet as nginx configuration.  Do not forget to set path to certificate and key 

.. 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/;
        }

        location /admin/ {
            error_log /var/log/nginx/admin.error.log;
            access_log /var/log/nginx/admin.access.log;
            proxy_pass http://127.0.0.1:8004;
        }
    }

Replace ``server_name`` with the name of your server and provide your ssl certificate and key. Then reload nginx. Admin server will then be accessible at ``/admin`` endpoint (as in https://example.com/admin).

.. note::

    Note that ``proxy_pass`` directive for admin server does *not* end with slash (``/``).

Migrating from basic installation
---------------------------------

Migration from basic installation is fairly straightforward. Go to your ``contacts`` directory and run

.. code-block:: bash

    docker-compose down

Then follow this guide (set up configuration files and edit ``docker-compose.yml`` file). Before starting the services (but after changing ``docker-compose.yml``) run also the following command in the directory with ``docker-compose.yml``.

.. code-block:: bash

    docker-compose pull

This will download the new versions of the services.

Admin server basics
-------------------

You can connect to your admin server at https://example.com/admin (change example.com to your server address). You can login with the username and password you provided in the configuration file.

After logging in, you will see status of your services. You can click on details and see their metrics or environment.

.. note::

    Contact server's *Logging* tab will show ``"error": "Couldn't find Logback JMXConfigurator-MBean"``. You can safely ignore this.

The control part for Contact server is in *JMX* subpage. Click on acrobits.jmx section. This will display three options: *AdminOperations*, *AvatarService*, *DataViewer* and *SelectiveLogging*. You can safely look through *DataViewer* which does not modify the data and try operations there. Be careful with *AdminOperations*. Remaining groups *AvatarService* and *SelectiveLogging* contain functions that are not intended to be available for Acrobits customers. Please do not use functions in *AvatarService* and *SelectiveLogging* groups.

*AdminOperations* are operations that you can use for single deletion of a device or a whole account. You can also find here operations for cleaning up all database records when you need to start from scratch

Examples of usage:

#. *deleteAccount* - When you need to delete an account you need to know its database id first. The way how to get the database id is using function *findAccountDevicesByUserNameAndCloudId* from *DataViewer* group. When you call this function then you get back account object. Copy the value of "_id" key from the the object and use it as input parameter of *deleteAccount* to delete the account

#. *deleteDevice* - When you need to delete a device you need to find "id" of the owning account (follow steps from previous point) and you need to know the "deviceId" that you can find in displayed account json object (in devices array). Use those values as input parameters to delete the device and related contact blocks

*DataViewer* Using these operations you can browse data stored in your database. These operations are not modifying database state so it is safe to use them