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

1. Create a directory on the target host (/opt/dfakto/proPilot, C:\Program Files\dFakto\proPilot, …)

2. Create a file named docker-compose.yml with the following content as a base.

   DOCKER

   services:
   
     propilot-db:
       image: mariadb:11.8.2
       container_name: propilot-db
       restart: always
       environment:
         MARIADB_ROOT_PASSWORD: 'yourRootPassHere'
         MARIADB_DATABASE:      'propilot_global'
         MARIADB_USER:          'propilot'
         MARIADB_PASSWORD:      'yourPassHere'
       volumes:
         - mariadb_data:/var/lib/mysql
       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=yourPassHere"
         DFAKTO_PROPILOT_HTTP_PORTS: 8080
         Logging:LogLevel__Default: Information
         identityServer__Host: https://accounts.yourCompany.com/auth/realms/propilot
         identityServer__clientId: dev
         identityServer__ValidAudience: account
         identityServer__keycloakHost: https://accounts.yourCompany.com
         identityServer__keycloakSecret: SecretGuidFromKeyCloak
         identityServer__FirstAdminEmail: emailSetForTheAdmAccountInKeyCloak
         
         Sentry__Dsn: https://yourPublicKey@o0.ingest.sentry.io/yourProjectId
         Sentry__Environment: production
         Sentry__Debug: true
         Sentry__SendDefaultPii: true
         Sentry__threshold: "ERROR"
         Smtp__SmtpDeliveryMethod: SpecifiedPickupDirectory
         Smtp__From: "noreply@yourCompany.com"
         Smtp__PickupDirectoryLocation: "/some/folder/location"
         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: 
         mariadb:
           condition: service_healthy
       restart: always
       volumes:
         - ./propilot:/app/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.yourCompany.com/auth/realms/propilot
         NG_APP_APPLICATION_AVAILABLE_LANGUAGES: "en,fr"
       ports:
         - "4200:80"
       restart: unless-stopped
       
   volumes:
     mariadb_data:
   

Adaptations

adapt the docker-compose file to suit your needs.

For instance, you may want to add the Keycloak (or other identity server) part in the above file.

Other elements to adapt

• MARIADB_ROOT_PASSWORD

• MARIADB_PASSWORD

• AppSettings__connectionString

• identityServer__Host

• identityServer__keycloakHost

• 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

Launch the application

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

⚠️ As Reminder, you won’t be able to connect to the application if you haven’t created an “adm” user in Keycloak first. This is because we need a first admin user to enter the application.

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.

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

Connect to the correct DB:

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.

Test the back-end

1. Make sure that the application is started

2. The following url should work (replace localhost by your domain name if necessary):
   http://localhost/api/info

3. The page is not html formatted but it must contain the back-end version of proPilot (e.g. ProPilot API VX.X.X)