proPilot installation and configuration

This document explains how to install proPilot on a machine.
Please read the instructions carefully, and follow the steps in the defined order.

Prior to installing proPilot, make sure to satisfy the requirements described in the dedicated document. All elements must be installed and preconfigured before proceeding to the installation of proPilot

Containerized deployment

The recommended way to deploy proPilot is to use the containerized approach.

But as explained in the requirements document, proPilot supports multiple options to handle SSO, so the identity server is not part of the installation file hereafter. To install Keycloak or any other Identity server solution, refer to the installation guide of your vendor.

Create a directory on the target host (/opt/dfakto/proPilot, C:\Program Files\dFakto\proPilot, …)
Create a file named docker-compose.yml with the following content as a base.

YAML

services:

  propilot-db:
    image: mariadb:11.8.2
    container_name: propilot-db
    restart: always
    environment:
      MARIADB_ROOT_PASSWORD: 'rootPassHere'
      MARIADB_DATABASE:      'propilot_global'
      MARIADB_USER:          'propilot'
      MARIADB_PASSWORD:      'propilotDBPass'
    volumes:
      - mariadb_data:/var/lib/mysql
      - ./docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d:ro
    command:
      - --sql-mode=ANSI_QUOTES
      - --lower_case_table_names=1
    healthcheck:
      test:
        [
          "CMD",
          "healthcheck.sh",
          "--connect",
          "--innodb_initialized"
        ]
      interval: 10s
      timeout: 5s
      retries: 5

  propilot-api:
    image: quay.io/dfakto_org/propilot/propilot-api:${PROPILOT_API_VERSION}
    container_name: propilot-api
    environment:
      AppSettings__connectionString: "Server=propilot-db;Port=3306;Database=propilot_global;User Id=propilot;Password=propilotDBPass"
      AppSettings__IsDevLicenceCheckDisabled: true
      DFAKTO_PROPILOT_HTTP_PORTS: 8080
      Logging__LogLevel__Default: Information
      
      # First WriteTo: Console
      Serilog__WriteTo__0__Name: Console
      Serilog__WriteTo__0__Args__outputTemplate: "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff} {Level}] {Message:lj} <s:{SourceContext}>{NewLine}{Exception}"
      Serilog__WriteTo__0__Args__theme: "Serilog.Sinks.SystemConsole.Themes.AnsiConsoleTheme::Code, Serilog.Sinks.Console"

      # Second WriteTo: File
      Serilog__WriteTo__1__Name: File
      Serilog__WriteTo__1__Args__path: "/var/log/propilot/propilot.txt"
      Serilog__WriteTo__1__Args__rollingOnFileSizeLimit: "true"
      Serilog__WriteTo__1__Args__fileSizeLimitBytes: "10000000"
      Serilog__WriteTo__1__Args__retainedFileCountLimit: "10"
      Serilog__WriteTo__1__Args__formatter: "Serilog.Formatting.Json.JsonFormatter, Serilog"
  
      identityServer__Host: https://accounts.test.dfakto.com/auth/realms/propilot
      identityServer__clientId: dev
      identityServer__ValidAudience: account
      # -- set the 2 variables only if you use the master mode
      #identityServer__keycloakHost: https://accounts.your-keycloak.com
      #identityServer__keycloakSecret: the-secret-configured-in-keycloak
      identityServer__FirstAdminEmail: your-proPilot-admin-email@your-company.com
      
      Sentry__Dsn: https://yourPublicKey@o0.ingest.sentry.io/yourProjectId
      Sentry__Environment: developmen
      Sentry__Debug: true
      Sentry__SendDefaultPii: true
      Smtp__SmtpDeliveryMethod: SpecifiedPickupDirectory
      Smtp__From: "./"
      Smtp__Host: null
      Smtp__Port: null
      Smtp__UserName: null
      Smtp__Password: null
      AppFolders__TreeNodeCodeFileBasePath: "ProPilot/nodes"
      TempFolder__TempFolder: "ProPilot/temp"
      AppFolders__PrivateKeysPath: "ProPilot/keypath"
    ports:
      - 5555:8080
    depends_on: 
      propilot-db:
        condition: service_healthy
    restart: always
    volumes:
      - ./propilot:/app/ProPilot
      - propilot_logs:/var/log/propilot

  propilot-ui:
    image: quay.io/dfakto_org/propilot/propilot-ui:${PROPILOT_UI_VERSION}
    container_name: propilot-ui
    environment:
      NG_APP_PROPILOT_API_URL: http://propilot-api:8080
      NG_APP_AUTH_ISSUER: https://accounts.your-sso.com/auth/realms/propilot
      NG_APP_APPLICATION_AVAILABLE_LANGUAGES: "en,fr"
    ports:
      - "4200:80"
    restart: unless-stopped
    
volumes:
  mariadb_data:
  propilot_logs:

Adaptations

adapt the docker-compose file to suit your needs.
you should at least search for “your-” in the above example, and replace the default values with valid values.

For instance, you may want to configure Keycloak (or other identity server).

Here are the main elements to adapt

MARIADB_ROOT_PASSWORD
MARIADB_PASSWORD
AppSettings__connectionString
identityServer__Host (SSO)
identityServer__keycloakHost (Master mode only)
Sentry (see next section)
Replace the “accounts.yourCompany.com” by the correct host.
Replace ${PROPILOT_API_VERSION} by the correct version
Replace ${PROPILOT_UI_VERSION} by the correct version
identityServer__keycloakSecret
SMTP configuration (can be “Network" or “SpecifiedPickupDirectory“)
- if SpecifiedPickupDirectoryis chosen, you must configure the Smtp__PickupDirectoryLocation (and leave the other field to null: host, port, username, password)
- if Network is chosen, you must leave the Smtp__PickupDirectoryLocation to null, and configure the other fields (host, port, username, password).

Sentry

Sentry is a developer-first error tracking and performance monitoring platform. This configuration is optional. See official documentation for more information.

e.g.

environment - Environment is used for sentry (Ex: production)

sentryDsn - Sentry Data Source Name. Here how to get your project sentry DSN

DB initialization

in the same folder as your docker-compose file you must create a sub folder named “docker-entrypoint-initdb.d”.

Inside that sub-folder, create a file named “init.sql”, with the following content:

SQL

-- Create user if it doesn't exist and grant global privileges
CREATE USER IF NOT EXISTS 'propilot'@'%' IDENTIFIED BY 'propilotDBPass';
GRANT ALL PRIVILEGES ON *.* TO 'propilot'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Launch the application

When launched, the application will automatically create the necessary tables.

⚠️ As a Reminder, you won’t be able to connect to the application if you haven’t configured the admin user email address. This first admin user must exist in Keycloak (or in your SSO solution). This is because we need a first admin user to enter the application.
See docker-compose file above.

identityServer__FirstAdminEmail: your-proPilot-admin-email@your-company.com

Configure operational parameters in the global database

Technical configuration files (appsettings.json) were designed to launch the application (DevOps oriented), but when the application is up, operational information must also be configured.

You can interact with the DB using a command similar to this one. You will be prompted to enter the root password, and will then be able to type SQL commands.

SQL

docker exec -it propilot-db mariadb -u root -p

Connect to the correct DB:

SQL

MariaDB [(none)]> USE propilot_global;
Database changed
MariaDB [propilot_global]> SHOW TABLES;

Use standard SQL commands to update the “Config” table in the global database, and setup the following entries according to your needs.

Key	Sample	Comment
`AdminMail`	`propilotadmin@yourcompany.com`
`SmtpSenderEmailAddress`	`noreply@yourcompany.com`
`AddReplyToAdminInAllEmails`	false
`ApplicationName`	`proPilot`	If you want to customize the application name in your company.

Test the back-end

Make sure that the application is started
The following url should work (replace localhost by your domain name if necessary):
http://localhost/api/info
The page is not html formatted but it must contain the back-end version of proPilot (e.g. ProPilot API VX.X.X)