# 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.