Headless BI Setup PivotData Microservice deployment

PivotData microservice is a Microsoft .NET (NET8) application that can be deployed on the following platforms:

• Windows: Win10/11, Windows Server 2012+
• Linux: Ubuntu Server (20.04+), Debian, RedHat, Mint, CentOS, Oracle Linux (any Linux that is supported by NET8)
• Mac OS
• Any other environment that supports containerized apps (a docker image, Linux/amd64)

Prerequisites

1. Install ASP.NET Core 8.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.6.
     For for Ubuntu Server:

     $ sudo apt-get update
     $ sudo apt-get install -y wget fontconfig fontconfig-config fonts-dejavu-core libbsd0 libfontconfig1 libfontenc1 libfreetype6 libjpeg62-turbo libmd0 libpng16-16 libx11-6 libx11-data libxau6 libxcb1 libxdmcp6 libxext6 libxrender1 sensible-utils ucf x11-common xfonts-75dpi xfonts-base xfonts-encodings xfonts-utils
     $ wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.buster_amd64.deb
     $ sudo dpkg -i wkhtmltox_0.12.6-1.buster_amd64.deb

   • 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.6 and then simply double-click on it (you might need to move it out from "Downloads" folder. Alternatively the same can be done in a terminal:
     

     sudo installer -pkg wkhtmltox-0.12.6-2.macos-cocoa.pkg -target /

   • 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 ASP.NET NET8 app - the only difference that you already have complied ('published') cross-platform 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 from a zip file

Running in a Docker container

Starting from version 1.4.0 you can use official nreco/pivotdataservice docker image (derived from mcr.microsoft.com/dotnet/aspnet:8.0, Linux x86 architecture only, ARM is not supported - but can be supported if needed). To run PivotData microservice in a docker container:

1. Ensure that docker is installed (if not: Docker Engine 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 see examples and use it as a base URL for accessing PivotDataService web API endpoints.

How to use appsettings.json from local server's directory ./config/ (mounted as a volume):

sudo docker run -p 5000:5000/tcp -e APPSETTINGS_JSON=/config/appsettings.json -v ./config:/config nreco/pivotdataservice

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 that are generated and executed by the reporting engine)