Technical needs met when standing up FOLIO installs

Owned by James Fuller
Last updated: Jan 19, 2022 by Ingolf Kuss

This is a summary of the concerns raised by the SysOps SIG in their discussions on 2021-08-27 and 2021-09-03. The discussion arose following the experiences that SysOps had during their efforts of installing the Juniper R2-2021 release. It largely pertains to the on-premise installation procedure on a Kubernetes cluster (or Rancher + k8s cluster). The scope of these concerns is system installation (deployment), technical documentation for installing a FOLIO system (maybe misleadingly called "operational documentation" below) , module upgrades and logging. The concerns raised here are not addressing issues of performance of a running system or of storage and other resource usage of a running system. In other words, this is about installation, not about operation.

The issues summed up here had been presented to the Technical Council on 2021-09-08.

Many of these issues overlap, and one common thread is the need to reduce the manual processes and the complexity so that it is easier for people to contribute new modules/code to folio and to help increase the ability to add features and/or changes to folio without the need for large releases.

Based on the SysOps SIG meeting on 20210827 

  1. Improve operational documentation
    1. Consistent and project wide method for documenting
      • Ports
      • Data connections (postgres, elasticsearch, kafka, object store)
      • Environmental/runtime variables
      • Configuration entries
      • Upgrade instructions
    2. General operational documentation
  2. Allow OKAPI to discover services
  3. Allow for a simpler basic install
    • Reduce the scope of FOLIO core
      • have 3 Apps maximum
    • Allow for a simpler addition of Apps
    • Simplify complex dependency graph
    • Enforce Domain Boundaries that define an App; reduce dependencies
  4. Simplify Folio bootstrap process
    • Service Discovery
    • Importing of Module Descriptors
    • Enabling Modules for Tenants
    • Superuser provision
    • configuration process
  5. Document (or update existing) technical philosophy. For example:
    • We prefer Containers
    • We strive for continuous release and deployment; to follow recommendations for 12 factor applications
    • How we try to balance "Small Core" and "Complete Product"
    • How we handle Domain Boundaries (where APIs overlap, interact, and potentially duplicate) and improve contracts between modules
  6. Clear and consistent Semantic Versioning across the entire project
    • All modules and okapi have the same Major version number when APIs are compatible.
  7. Improve logging across the platform
    • A very small number of well documented patterns (we understand that Vertx, Springboot, and edge modules may need different patterns)
  8. Improve stance for agnostic hosting (we have cloud, on-premises, and local deployments; single server, multi server, and kubernetes deployments)