Analytics API Setup PivotData Microservice Documentation

PivotData microservice is a .NET Core application that can be installed on the following platforms:

• Windows: Win10/11, Windows Server 2012-2022
• Linux: Ubuntu (16.04 or newer), Debian, RedHat, Mint, CentOS, Oracle Linux (everything that is supported by NET6)
• Mac OS

Prerequisites

1. Install ASP.NET Core 6.0 Runtime (LTS)
2. Dependencies:
   • Windows
   • Linux
   • Mac OS
   • PDF export: no actions required (wkhtmltopdf binaries are shipped with PivotData microservice)

   • PDF export: install wkhtmltopdf version 0.12.4.
     For Ubuntu Server:

     $ sudo apt-get update
     $ sudo apt-get install libxrender1 fontconfig xvfb
     $ wget https://downloads.wkhtmltopdf.org/0.12/0.12.4/wkhtmltox-0.12.4_linux-generic-amd64.tar.xz -P /opt/
     $ cd /opt
     $ sudo tar xf wkhtmltox-0.12.4_linux-generic-amd64.tar.xz
     $ sudo cp /opt/wkhtmltox/bin/wkhtmltopdf /usr/bin/wkhtmltopdf

   • ODBC connector (only if you use it): install unixODBC (version 2.3.1 or higher).
     For Ubuntu Server:

     sudo apt-get update
     sudo apt-get install unixodbc

     Then, install ODBC driver(s) you need. Don't forget to register driver in odbcinst.ini and DSN in odbc.ini (if you use DSN). For more details, see setup instructions provided by driver's vendor.

   • PDF export: download wkhtmltopdf installer (.pkg) for version 0.12.4.
   • ODBC connector (only if you use it):

     brew install unixodbc

3. Extract files from zip (can be downloaded here): PivotData microservice binaries are located in PivotDataService folder.

Start a microservice

For testing purposes it is enough to extract PivotData microservice binaries to some folder and start it from the command line:

dotnet NReco.PivotData.Service.dll

This will start microservice web application with default binding for localhost:5000 by default (not accessible by external IP). You can change binding by specifying additional option:

dotnet NReco.PivotData.Service.dll --server.urls=http://0:0:0:0:5000

In production environment it should be deployed as any other .NET Core app - only difference that you already have complied 'published' binaries for framework-dependent deployment. More details about concrete deployment scenarious:

• Windows with IIS ASP.NET Core module
• Linux with Nginx
• Deploy to Azure Apps with zip

Running in a Docker container

Starting from version 1.4.0 we provide official nreco/pivotdataservice docker image (Linux x86 architecture only). To run PivotData microservice in a docker container:

1. Ensure that docker is installed (if not: Docker CE setup instructions).

2. sudo docker run -p 5000:5000/tcp nreco/pivotdataservice

3. Now you can open http://your_linux_server_hostname_or_ip:5000/ to review examples and use this URL as microservice web API endpoint.

How to create customized docker images with your own appsettings.json:

1. Create Dockerfile in the same folder with your appsettings.json file:

2. FROM nreco/pivotdataservice:latest
   WORKDIR /app
   COPY ./appsettings.json/ ./
   

3. Build your image:

   sudo docker build -t nreco-pivotdataservice -f ./Dokerfile .

4. Run:

   sudo docker run -p 5000:5000/tcp nreco-pivotdataservice

   Hint: you can override appsettings.json options with environment variables, for example:

   -e PivotDataService_Logging:LogLevel:NReco.PivotData.Engine='Debug'

   (this option enables logging of all database queries generated by OLAP engine)