Service Packaging Requirements

Owned by Preston Lee
Last updated: May 16, 2019
3 min read

The authoritative version of this document is now embedded within the HL7 Marketplace specification. It is partially replicated here for convenience only.

Services are declared to the Marketplace via a client such as the official web UI or other compatible application. Each service is further programmatically bootstrapped into an execution environment and MAY be subject to additional validation, depending on specific declared capabilities. All service implementations MUST be:

  • Containerized into a single, OCI-compatible image, with Docker as the gold standard and runtime verification tool.
  • Ephemeral. All persistent data MUST be saved to an external database and declared as a service dependency, if needed.
  • Programmatically Verifiable. Services providing standardized capabilities MUST support a mode for exercising declared APIs via a "smoke test" suite triggered via the marketplace. Service submissions failing to pass smoke test on declared capabilities will be automatically rejected. (Rationale: HSPC MAY provide these tests at its discretion. Tests specific to a Service or Version may be run as an out-of-band activity prior to submission to the Marketplace. Additionally, ISVs MAY run applicable test suite(s) on Service Versions prior to review and publication.) 
  • Horizontally Scaled. The number of concurrently running containers will usually be more than 1.
  • Dynamically Scalable. Instances are scaled up/down at at any time. Note: For HTTP services, the use of sticky sessions is highly discouraged, in favor of JWTs or similar lightweight session tracking for session state data. (TODO PRESTON: Add boolean for service autoscaling)
  • Single-Process per container task. If your service requires, for example, a single image to be run once as a web service and again as a separate worker node, these alternate entry points SHOULD be declared in the capabilities document.
  • Domain Name (DNS) Agnostic. No domain name, SSL/TLS context, and locale-specific settings may be hard-coded into the service.
  • Unencrypted. HTTP services will be encrypted at a separate layer providing SSL/TLS as a separate service providing reverse proxy load balancing.
  • Compute Constrained. You MUST define the maximum per-task RAM requirement at image publication time, and manage your use of memory wisely.
  • x86-64. 32-bit binary are obviously fine as well, but we do not support other CPU architectures.
  • Self-Bootstrapped. Every image must be able to bootstrap itself into a functional, default state with zero human intervention. This is declared in the capabilities document and is used for service validation at publication time, local consumer evaluation testing, and for seeding production deployments.
  • Stoppable at container shutdown time within 60 seconds.
  • Good Citizens executing in good faith that they do exactly what they say.
  • Health & Traceability: Process monitoring internal to the container SHOULD support the prevailing standard of practice for the software language/framework in use.
  • Logging: Services SHOULD log, and when they do, they SHOULD log to standard out/error and MUST NOT be written to the file system. PHI/PII MUST NOT be logged under any circumstance.

Services MUST NOT be:

  • Data Payloads. Service images are for software only. Do not bundle large data files into the software image. Rather, define a container initialization step that downloads requisite data or pulls them from a separate database.
  • Hardware Dependent. This is software that requires specific physical daughter cards, dongles, CPU serial numbers etc. We do not support binding to hardware dependencies at this time.


Best Practices

Services are encouraged to be:

  • SSO Aware using OpenID Connect and/or SAML. If your service requires user logins, declare it in your conformance statement as needing an SSO IDP configuration  at run-time.
  • Provisionable via IETF SCIM 2 API implemation for individual and batch user and group management, used by ActiveDirectory and other identity management systems.
  • Profilable via [OpenTracing](http://opentracing.io), which supports tracking of user session context *across* services for comprehensive system benchmarking.
  • Incorruptible in the event they are killed without notice. 
  • Offline-Friendly to environments where no Internet access is permitted, whenever possible.