Keysat
c7ce44d963
Workstream A–C substrate for the Ten31 agentic system: - A1: docs/crm-overview.md; CLAUDE.md conventions + guardrail #9 - A2: additive/reversible core migration (canonical_entities, entity_links, interaction_log, relationship_edges, soft-delete) + ledgered runner - B1/B3: chunking + deterministic entity resolution (backend/ingest) - B2: dense (bge-m3) + BM25 sparse ingest to Qdrant crm_chunks - C: CRM MCP server (reads, retrieval modes, logged writes) — no outbound tools - docs: redaction/re-hydration, Gmail enablement runbook - synthetic test data; .env.example; housekeeping (.gitignore, untrack crm.db, drop legacy files + start9/0.3.5) Verified end-to-end on synthetic data + live Sparks (hybrid > dense on entity queries). Real backfill runs on Ten31 infra; index holds synthetic data only. Branch snapshot also captures pre-existing working-tree changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
# 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.
|