TABLE OF CONTENTS

1. System requirements

  • OS - any which supports Docker (Linux is recommended)

  • RAM - 8 Gb minimum (16 Gb recommended)

  • CPU - 2 cores minimum (6 cores recommended)

  • Storage - 20 Gb minimum

Applications:

  • Docker v17.06+ (For installation follow its official documentation)

  • Git


2.  Installation steps

Сlone this project and set up a mirror of the source repository xm2-config for local configuration, make git clone --mirror project xm2-config

$ git clone https://github.com/xm-online/xm-online.gi

  • and set up a mirror of the source repository xm2-config for local configuration


cd xm-online/assets/


$ git clone --mirror https://github.com/xm-online/xm-ms-config-repository.git


From the xm-online/assets/ run docker to start containers defined.

  • start swarm for work docker stack

$ docker swarm init

  • start service XME.digital2

$ docker stack deploy -c docker-compose.yml xm2local


If it is the first time you are using those images, it will first download the images from hub which may take some time.

If nothing goes wrong you should see a couple of containers are running on your machine. To see them you can type:


$ docker ps


$ docker service ls



In this example, we simply map port 80 of the host to port 80 of the Docker (or whatever port was expos in the docker-compose.yml) Verify the deployment by navigating to your server address in your preferred browser.


127.0.0.1:80

or

<ip>:80


Picture 2. Login screen


,Note: some browsers, for example, Chrome, prevent accessing the URL localhost:80 so we recommend using direct IPURL


The ports of all the services like Postgresql, Kafka etc. were intentionally changed to custom ones to not to conflict with the default ones that may be installed and running on the machine. For example, to connect to Postgresql here is the credentials:

postgresql:

       image: postgres:9.6.2

       networks:

           - xm2

       ports:

           - 5432:5432

       volumes:

           - ./:/docker-entrypoint-initdb.d/

       environment:

           - POSTGRES_USER=postgres

           - POSTGRES_PASSWORD=postgres

       deploy:

           mode: replicated

           replicas: 1

           restart_policy:

               condition: on-failur


To get credentials of other services you may want to see docker-compose.yml and docker logs


3. Start/Stop and health check

To stop Docker swarm use command:

$ docker stack rm xm2local


To start:

$ docker stack deploy -c docker-compose.yml xm2local


Also you can check active services in consul by url: http://<IP>:8500 and ensure that next services are active (green):

  • balance

  • config

  • consul

  • dashboard

  • entity

  • gate

  • timeline

  • uaa


4. Debugging

For debugging you can open logs service

$ docker service logs {SERVICE_ID}


Sometimes you may need to bash into a specific container for debugging purposes. To do that:

$ docker exec -it {CONTAINER_ID} bash


In order to debug particular xm microservice:

Update docker file in microservice you want to debug:

{microservice-name}/src/main/docker/Dockerfile


Add to JAVA_OPTS variable (or simple pass this options after java -jar myservice.jar -Dagentlib:...):

-Dagentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000


Add port to expose command (or use any other options from Docker to expose port for container):

EXPOSE 9999 8000


Update docker-compose.yml file and add/update microservice configuration you want to debug:

ports:
     - 8000:8000


(Intellij idea) Run Remote configuration Open microservice you previously added debug to, In Run/Debug Configuration click on "+" button and find "Remote" configuration, Update "Port" field inside Remote configuration with value 8000, Click Apply and Ok, Run this Remote configuration from menu by click on the green "->" button.

For checking microservice logs you can run

$ docker service logs {SERVICE_ID}


Sometimes you may need to bash into a specific container for debugging purposes. To do that:

$ docker exec -it {CONTAINER_ID} bash