Advanced Installation

The method described in the installation guide 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 the simple installation guide. 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:

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

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

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

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

---
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.

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 Key generation for SSO.

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

---
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:

docker-compose up -d

The next step is setting up reverse TLS proxy. The process is similar to the one described in the regular installation guide. The difference is an additional location section.

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

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

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.

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:

  1. 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

  2. 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