Skip to main content

Build

This document explains how to build and run the application from the source code, but also how to package and distribute it.

Prerequisites​

  • Node.js v22.7.1+ with npm (tested) or pnpm or yarn for building the application's components and the extensions.
  • Python v3.11+ for building the Python extensions.
  • The back-end module requires Java v17+, which should be accessible as a first Java runtime through the PATH, when generating the OpenAPI client code.
  • When building the container image, a Docker-like application should be up and running.

Compiling and building​

The following commands will install dependencies and build the components. They should be run from the root package.json file.

  • Run the traditional npm run install script for resolving the hereby package dependencies.
  • Run the npm run prerequisites script for resolving all submodules' dependencies: do not run individually the npm install script on every module, because it will not properly install the "back-end" and "electron" components since the prerequisites npm script resorts to the --install-link option, which installed the "shared/back-end" module dependencies.
  • Run the npm run build script for building all artifacts.

Most of the artifact files are located under the build directory, which is a symbolic link pointing to the electron/build directory.

Cleaning​

The following commands enable cleaning up the project. They should be run from the root package.json file.

  • Run the npm run clean script for cleaning all artifacts coming from compilation and previous builds.
  • Run the npm run reset script for resetting the state of the project's files to their git initial state — in particular, this deletes the node_modules directories.

Versions​

The versions of the various components are specified through the root package.json file via the config.applicationVersion, config.apiVersion and config.sdkVersion properties:

  • config.applicationVersion: the version of the Electron application ;
  • config.backEndVersion: the version of the back-end application ;
  • config.frontEndVersion: the version of the front-end application ;
  • config.apiVersion: the version of the API and its OpenAPI web services contract ;
  • config.sdkVersion: the version of the SDK.

Whenever changing any of those versions, think of running the npm run updateVersion script from the root directory to propagate the version changes to the relevant submodules, which updates the src/constants.ts file accordingly and the SDK version and the extensions' dependency version accordingly.

Back-end (server)​

Its source-code and scripts are located under the back-end directory.

All the commands specified in that section should be run from the back-end subdirectory and all resource locations are expressed from that directory, unless stated otherwise explicitly.

Build​

  • To build the back-end from scratch, run the following command from the root folder: npm run back-end:prerequisites && npm run back-end:build.
  • To recompile it after having changed its code, run the npm run build script.

Run​

To run the back-end, run the npm run start script. The environment variables which have an impact over the execution as well as the commands and parameters are described by running the npm run start:help script.

You may access to the SwaggerUI relative the OpenAPI specifications, captured through the JSON openapi.json file, open the browser to the http://localhost:3001/swaggerui URL, 3001 being the back-end default port.

Development​

  • When changing the database Prisma schema:

    • run the npm run prisma:generate script to regenerate the Prisma client code,
    • then run the npm run prisma:update script to update the schema of the startup database file database.db and to add the new SQL migration script in the prisma/migrations directory (in case of a synchronization issue with the schema migration, read this article Make Prisma Ignore a Migration Change),
    • and then run the npm run prisma:seed script to update the settings table value startup database file database.db with its settings set to the latest version of the migration.

  • When changing the OpenAPI contract, run the openApi:generateOpenApi script to regenerate the openapi.json file.

    • Think of updating the config.apiVersion property.
    • The npm run openApi:typeScript:generateAndPackage script generates the TypeScript OpenAPI client library into the directory ../generated/openapi/typescript-fetch.
    • The npm run openApi:python:generateAndPackage script generates the Python OpenAPI client library into the directory ../generated/openapi/python.
    • The npm run openApi:generateAndPackage script generates the 2 previous packages.

  • Whenever the database schema changes, a file in the secrets or assets directory changes, run the npm run build:copy script to update the Electron application dist directory.

API web services client library publication​

To publish a new version of the API web services client library, run the npm run wsClient:publish script, after having built the libraries via the previous openApi:generateAndPackage script:

  • for publishing the Node.js package on npm, use the npm login --scope=@koppasoft command to log in first ;
  • for publishing the Python package on PyPi, declare an API token at https://pypi.org/manage/account/token/ beforehand.

Extensions​

The SDKs and extensions and scripts are located in the extensions directory and the commands in the rest of this section should be run from that directory:

  • the SDKs are in the sdk subdirectory ;
  • the extensions are in the instances subdirectory.

For building the SDKs and extensions:

  • run the npm run sdk:build script to build the SDKs ;
  • run the npm run instances:build script to build the extensions ;
  • run the npm run build script to build both.

When a new version should be applied to all extensions, run the npm run incrementVersion script to increment their minor version.

SDKs publication​

To publish a new version of the SDKs, run the npm run sdk:publish script, after having built the SDKs via the sdk:public:build script:

  • for publishing the Node.js SDK package on npm, use the npm login --scope=@koppasoft command to log in first ;
  • for publishing the Python SDK package on PyPi, declare an API token at https://pypi.org/manage/account/token/ beforehand.

Front-end (web)​

Its source-code and scripts are located under the front-end directory.

All the commands specified in that section should be run from the front-end subdirectory and all resource locations are expressed from that directory, unless stated otherwise explicitly.

Build​

  • To build the front-end component from scratch, run the following command from the root folder: npm run front-end:prerequisites && npm run front-end:build.
  • To recompile it after having changed its code, run the npm run build script.

Run​

To run the front-end component, run the npm run start script.

Shared​

Its source-code and scripts are located under the shared directory. It only contains a back-end folder, which contains code common between the "back-end" and "electron" modules.

  • Run the npm run build script to build it, which will compile the code.

Electron​

Its source-code and scripts are located under the electron directory.

  • Run the npm run start script to start it on the local machine.
  • Run the npm run build script to build it for the same target OS as the hosting machine, which outputs a runnable artifact inside the dist directory.
  • Run the npm run package script to package it for the same target OS as the hosting machine.

Container image​

The container image specifications are classically defined through the Dockerfile file and the ignored files through the .dockerignore file.

Build​

To build the container image of the back-end application via Docker, which also embeds the front-end application, run the npm run docker:build script from the root directory, which creates an image with the koppasoft/picteus:latest tag.

Publish​

To publish a new version of the container image, run the npm run docker:publish script from the root directory, which pushes it against Docker Hub.

Run​

Refer to container.md for running the container.

Packaging and distributing​

The Electron application:

  1. is packaged via the npm run package script: this invokes the previously mentioned Electron package npm script ;
  2. is distributed via the npm run distribute script — which also invokes the previous one —, which signs, zips and notarize the application distribution package on macOS, which should be executed with the following environment variables set, when run on macOS:
  • MACOS_APPLICATION_CERTIFICATE_BASE64_CONTENT: the base64 encoded content of the application certificate. This content is obtained via the base64 -i <certificate.p12> command, where <certificate.p12> is the path of the "Developer ID Application" certificate file in P12 format ;
  • MACOS_APPLICATION_CERTIFICATE_PASSWORD: the password of the previous certificate ;
  • MACOS_NOTARIZE_APPLICATION_PASSWORD: the Apple application-specific password related to the Picteus entry, used to notarize the application package ;
  • PICTEUS_CHROME_EXTENSIONS_TOKEN: the Personal Access Token (PAT) value for access the private GitHub repository containing the Chrome extensions ;
  1. is deployed via the npm run deploy script, which uploads the previously generated application distribution package: the gcloud login command should have been run beforehand, with GCP credentials having permissions over the destination GCS bucket, or with the CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE environment variable set with the contents of a GCP account service key with writing permissions over the GCS bucket.