/state-space-packaging

Primary LanguageMakefileApache License 2.0Apache-2.0

This project contains the packaging for the IAB PrivacyChain system and the Hyperledger Fabric upon which the v0.0- and v1.0-series of PrivacyChain is built.

Introduction

A filesystem hierarchy standard defines components installed. This allows both persons and computers to understand what to expect both from the underlying platform, describing the current system, but also where to place platform or application elements in the future.

The tenets outlined below follow the themes and concepts which are outlined in the Linux Filesystem Hierarchy Standard 3.0. We have also tried to be faithful to the application layout decisions made by the underlying platforms (e.g. by Hyperledger Fabric.

Naming Conventions

The naming convention outlined here pertains substantially to the packaging of PrivacyChain and Hyperledger Fabric. Where other aspects of naming are described, they are incidental and provided for color & context.

Available Conventions

Convention Applicable Where Examples
lower case special-case of kebab-case
kebab-case application artifacts _files & directories
snake_case is reserved to intra-application artifacts functions & namespaces
CamelCase same Class and type objects
UPPER CASE rare, for constants and WARNINGs

The Two Systems

There are two systems being delivered by the packaging herein.

The Hyperledger Honorific

The Hyperledger umbrella project of The Linux Foundation tends to keep the honorific Hyperledger in front of all of the different sorts of hyperledger projects that they sponsor. Indeed, all of the hyperledger projects share the same undifferentiated publication arena at GitHub. One could envision trading off one hyperledger technology for another depending upon the maturity, capability or feature-function affordances offered. Today, PrivacyChain uses Hyperledger Fabric. The filesystem hierarchy standard is faithful to the Hyperledger Project's use of the honorific hyperledger, thus preferring the term Hyperledger Fabric over pure name Fabric from the sponsors, IBM. This is preference is reflected in filesystem naming conventions as well.

Examples of this in material form are the directories: /etc/hyperledger/fabric, or /opt/hyperledger/fabric.

The PrivacyChain Brand as Application Name

In contrast, the PrivacyChain, project does not have such a branded honorific. The brand name is atomic. Semanticists in the audience will note that the privacy chain is not about developing privacy, but rather about the recordation and publication of documentary artifacts in service of regulatory compliance globally. The brands PrivacyChain and AudienceChain are used instead of these other more ponderous terms.

However, the convention in the Unix-type (e.g. Linux) systems upon which the PrivacyChain system will be deployed is to use lower case or kebab-case for application artifacts (e.g. files & directories). The use of snake case or CamelCase is reserved to intra-application artifacts (e.g. programming language objects, configuration objects, etc.).

Examples of this in material form are the directories: /etc/privacychain, or /opt/privacychain.

Containerization

The packaging and the filesystem hierarchy standard facilitates containerization by separating the system-independent and read-only filesystem elements, e.g. …/bin, …/lib and allies, from the system-dependent and instance-unique elements, e.g. /etc. Also segregated are the variable-sized storage areas which contain the data of the application, e.g. /var. The FHS elaborates these design decisions and the reasoning behind them. They are recited here in limited form to provide context and where the usage here differs extends the standard.

Nomenclature

The nomenclature from the GNU project is used where appropriate. The nomenclature follows the underlying FHS, thus indicating a preferred variable name for each denoted filesystem element. It is summarized here.

Directory Value Scope & Purpose
prefix / always (root), except for devel, test & in-situ installation
bindir $(prefix)/bin contains executables
sbindir $(prefix)/sbin not used
libexecdir $(prefix)/libexec not used, but prefer $(pkglibexecdir)
_lib lib or lib64 as used by the operating sy stem
libdir $(prefix)/$(_lib) shared libraries & development components
libarchdir $(libdir) with the architecture honorific, if applicable
libpuredir $(prefix)/libs without the architecture honorific
sysconfdir /etc the configuration area, system-dependent,
localstatedir /var the variable-sized area, is read-write
--- ---
pkgsysconfdir $(sysconfdir)/$(name) the application-specific configuration area, this is small and readonly
pkglocalstatedir $(localstatedir)/$(name) the applications's state, this can be written and may be large
pkglibexecdir $(libpuredir)/$(name) is preferred over the libexec particle, one level up

The Filesystem Hierarchy Standard

Configuration

The configuration area contains

Path Scope Contains
/etc/hyperledger/fabric Hyperledger Fabric directories msp and tls
/etc/privacychain PrivacyChain same

Installation Area

The application installation area is /opt.

Path Scope Contains
/opt/hyperledger/fabric Hyperledger Fabric configurations & certificates
/opt/privacychain PrivacyChain same

Data Storage

Path Scope Contains
/var/hyperledger/fabric Hyperledger Fabric blocks, and production
/var/privacychain PrivacyChain consent & data transfer records

This is somewhat at variance with the FHS which guides that application state should be in directories within /var/lib. Our expectation, being as these are blockchain-based projects with potentially unlimited storage needs, that the application data directories will need to be served from storage systems that are strong enough to scale towards that infinite future. Obviously that's a core problem in the blockchain concept itself; but until such time as this is resolved by technology, policy or fiat, the filesystem hierarchy will have to facilitate very very large storage within the application design plan, e.g. IPFS or Ceph.

The Great Packagers

RPM Systems

This would be Fedora- and Red Hat- based systems.

APT Systems

This would be distros like Ubuntu, Debian. As time and availability permit. Perhaps you would contribute here.?

Other

This would likely be support for those who wish to develop & test on other gear. Perhaps you would contribute here.?

None

Some installations wish to have their source code hooked up directly to production through a CI/CD process without an intervening packaging step. This configuration is not uspported (yet, at this time). Perhaps you would contribute here.?

References

Security

This repo offers packaging capabilities in support of the State Space reference implementation of the IAB PrivacyChain Technology Specification. As such, this project does not have any direct security concerns.

However, good source code supply chain management practices should be used when building and deploying this software. This includes at least the use of a verified chain-of-custody build system from the git-managed sources through the use of signed packages and repositories in deployment. The description of such methods are beyond the scope of this overview presentation. The point is that as code is deployed, you should know what you have built and where you got the components that you are deploying.

Contribute

Please refer to contribution instructions for information about how to get involved. We welcome issues, questions, and pull requests. Pull Requests are welcome.

Current work with modern-generation tooling, e.g. circa Fedora 36+ and GCC 12+, is occurring around the thematic themed branches; e.g. 01.worthy-cupboard, 02.maximum-hammer and so forth.

Maintainers

You may contact us at least at state-space@yahooinc.com

License

This project is licensed under the terms of the Apache 2.0 open source license. Please refer to LICENSE for the full terms.