proof-of-work/start9-example-packaging/START9_PACKAGING_CHECKLIST.md

Start9 Packaging Checklist (0.3.5 style)

This checklist is written for the StartOS 0.3.5 packaging flow used in this repo. Use it as an indicative template for other projects, not a literal one-size-fits-all script.

1) Required packaging scaffold (inside start9/<version>/)

• manifest.yaml
• Makefile
• Dockerfile
• docker_entrypoint.sh
• healthcheck.sh
• instructions.md
• icon.png (and/or icon.svg if desired)

Optional:

• scripts/ for package-specific helper scripts
• prebuilt artifacts (image.tar, .s9pk) generated by packaging

2) Project-specific values to change

In manifest.yaml:

• id
• title
• version
• description
• upstream-repo, support-site, marketing-site
• interfaces (port, protocol, TLS, UI flags)
• config (runtime env/config options)
• backup mounts/commands
• actions (if you expose maintenance actions)

In Makefile:

• package id/version variables
• image name/tag
• paths/targets used by make ... package

In Dockerfile:

• base image
• runtime dependencies
• app copy paths
• entrypoint/cmd

In scripts:

• read config/env from StartOS mount/env conventions
• write data only to mounted persistent directories

3) What must exist outside start9/

The wrapper is not fully standalone. It builds an image from your app source.

For this CRM package specifically:

• backend/server.py
• frontend/ (all static assets/UI)

These are copied in Docker build steps. In other projects, these paths, filenames, and build inputs can be different. This document is meant to show the pattern; each project must map to its own app layout.

4) Data + persistence checklist

• Persist DB/files under mounted data path (not container ephemeral path).
• Confirm backup/restore mounts and commands match the manifest volume names exactly.
• Verify restore can start app cleanly and preserve schema/data.

5) Network/interface checklist

• Confirm service listens on the internal container port expected by manifest.yaml.
• Confirm LAN interface protocol settings match actual service behavior (HTTP vs HTTPS/TCP).
• Confirm UI launches from StartOS Interfaces page without cert/protocol mismatch.

6) Build + install flow

1. Bump version in:
   • start9/<version>/manifest.yaml
   • start9/<version>/Makefile
2. Build package:
   • make -C start9/<version> package
3. Install resulting .s9pk in StartOS.
4. Start service and check:
   • health/logs
   • UI launch
   • persistence after restart
   • backup/restore smoke test

7) Reusable vs non-reusable parts

Reusable:

• overall folder structure and file roles in start9/<version>/
• packaging workflow (manifest + Makefile + Dockerfile + scripts)

Non-reusable without edits:

• app copy paths in Dockerfile
• app-specific env/config keys
• ports/interfaces/protocol values
• backup/restore commands tied to app data layout

8) Planned migration path to StartOS 0.4

When 0.4 is ready for your deployment, use this approach:

1. Keep 0.3.5 package stable as the production branch.
2. Create a parallel package folder for 0.4 (for example start9/0.4/).
3. Port wrapper files (manifest, Makefile, Docker packaging scripts) to the 0.4 schema/tooling.
4. Update interface/config/backup definitions to 0.4 expectations.
5. Build and install 0.4 package in a test server first.
6. Restore a real backup into 0.4 and validate:
   • app starts
   • UI works
   • data integrity is preserved
   • backup/restore still works
7. Only after successful validation, promote 0.4 package for primary use.

Notes:

• Keep database path and backup format stable where possible to make migration low-risk.
• If schema changes are required, add explicit migration steps and rollback steps before production cutover.