Skip to content
Pithyx

pithyx pack

View as Markdown

pithyx pack runs the checks of pithyx validate and, when there is no error, writes the app package <id>-<version>.pithyxapp: a gzip-compressed tar archive that you install in the Store or publish in a catalog. The same files always give the same bytes.

Synopsis

Section titled “Synopsis”
Terminal window
pithyx pack [project folder] [--frontend <folder>] [--out <path>] [--images]

Options

Section titled “Options”
Option Value Type Default Description
--frontend <folder> string dist The built frontend
--out <path> string the project The package file, or a folder for it
--images – boolean off Add backend/images/<arch>/<id>.tar for offline installs, saved with the local docker (save, or pull first, per architecture of the lock). Needs Docker with access to the registries; the images make the package large, and their bytes depend on Docker’s save format.

--out ending in .pithyxapp is the package file itself; anything else is a folder, which gets <id>-<version>.pithyxapp. A folder that does not exist yet is created, also the folder of a .pithyxapp path.

The package

Section titled “The package”
  • pithyx.json and icon.svg first, then every other path sorted by code unit.
  • frontend/ with every file of the built frontend except hidden ones.
  • README.md, README, LICENSE, LICENSE.md, LICENSE.txt when they exist at the project root.
  • With a backend: its Compose file and backend/images.lock.json.
  • CHECKSUMS: the SHA-256 of every other file in the format of sha256sum, so sha256sum -c CHECKSUMS checks an unpacked package.
  • With --images: backend/images/<arch>/<image id>.tar for each image and architecture of the lock. Each image is saved with docker save from your Docker when it has it (images of pithyx build): by its image id with the classic image store, by its manifest digest with the containerd image store (the default since Docker 29), with --platform where Docker knows it. Any other image is first pulled with docker pull --platform by its digest; an image of pithyx build (pithyx.local/...) is never pulled. The saved archive must hold the image config of the lock. When nothing works, the error lists every attempt. The archives make the package large, and their bytes depend on Docker’s save format.

Fixed modes, owners and times and no time in the gzip header make the archive deterministic.

Files

Section titled “Files”
File Access
everything validate reads read
the package (default <project>/<id>-<version>.pithyxapp) written, replaced if it exists
a temporary folder pithyx-images-* holds the saved images with --images, removed afterwards

Exit codes

Section titled “Exit codes”
Code When
0 Packed: Packed <path> (<n> bytes).
1 A finding of level error (Not packed: fix the errors above first.), no valid pithyx.json, or Docker fails with --images.
2 --out is neither a .pithyxapp file nor a folder, --images for an app without a backend or without a valid lock, or more than one project folder.

Findings

Section titled “Findings”

The same as pithyx validate; see Findings.

Examples

Section titled “Examples”
Terminal window
pithyx pack                          # ./com.example.notes-1.0.0.pithyxapp
pithyx pack --out dist-packages/     # into a folder, created if needed
pithyx pack --out notes.pithyxapp    # a file name of your own
pithyx pack --images                 # with the backend images for offline installs