From 04fc08c6552fa9ecf42f3bf6ff67b2e90e7a6e3a Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 29 Oct 2025 06:02:44 -0500 Subject: [PATCH] docs: add stack readmes and overview --- LifecycleStack/README.md | 23 +++++++++++++++++++ README.md | 49 ++++++++++++++++++++++++++++++++++++++-- SupportStack/README.md | 37 ++++++++++++++++++++++++++++++ ToolboxStack/README.md | 32 ++++++++++++++++++++++++++ 4 files changed, 139 insertions(+), 2 deletions(-) create mode 100644 LifecycleStack/README.md create mode 100644 SupportStack/README.md create mode 100644 ToolboxStack/README.md diff --git a/LifecycleStack/README.md b/LifecycleStack/README.md new file mode 100644 index 0000000..1640f1c --- /dev/null +++ b/LifecycleStack/README.md @@ -0,0 +1,23 @@ +# ♻️ LifecycleStack + +## Overview +LifecycleStack will eventually house the tooling and processes that manage the evolution of TSYSDevStack workloads—from ideation and delivery to ongoing operations. While the folder is in its inception phase, this README captures the intent and provides collaboration hooks for the future. + +## Focus Areas +| Stream | Description | Status | +|--------|-------------|--------| +| Release Management | Define staged promotion paths for stack artifacts. | 🛠️ Planning | +| Observability Loop | Capture learnings from SupportStack deployments back into build workflows. | 🛠️ Planning | +| Governance & Quality | Codify checklists, runbooks, and lifecycle metrics. | 🛠️ Planning | + +## Collaboration Guidelines +- Start proposals under `collab/` (create the directory when needed) to keep ideation separate from implementation. +- Reference upstream stack READMEs (Cloudron, Support, Toolbox) when describing dependencies or hand-offs. +- Keep diagrams and decision records in Markdown so they are versionable alongside code. + +## Next Steps +1. Draft an initial lifecycle charter outlining environments and promotion triggers. +2. Align with SupportStack automation to surface lifecycle metrics. +3. Incorporate ToolboxStack routines for reproducible release tooling. + +> 📝 _Tip: If you are beginning new work here, open an issue or doc sketch that points back to this roadmap so the broader team can coordinate._ diff --git a/README.md b/README.md index 63de2d7..7b4621c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,48 @@ -# TSYSDevStack +# 🌐 TSYSDevStack -TSYS Group Development Stack \ No newline at end of file +> A constellation of curated stacks that power rapid prototyping, support simulations, developer workspaces, and (soon) lifecycle orchestration for TSYS Group. + +--- + +## 📚 Stack Directory Map +| Stack | Focus | Highlights | README | +|-------|-------|------------|--------| +| 🛰️ CloudronStack | Cloudron application packaging and upstream research. | Catalog of third-party services grouped by capability. | [Open](CloudronStack/README.md) | +| ♻️ LifecycleStack | Promotion workflows, governance, and feedback loops. | Roadmap placeholders ready for lifecycle charters. | [Open](LifecycleStack/README.md) | +| 🛟 SupportStack | Demo environment for support tooling (homepage, WakaAPI, MailHog, socket proxy). | Control script automation, Docker Compose bundles, targeted shell tests. | [Open](SupportStack/README.md) | +| 🧰 ToolboxStack | Reproducible developer workspaces and containerized tooling. | Ubuntu-based dev container with mise, aqua, and helper scripts. | [Open](ToolboxStack/README.md) | + +--- + +## 🚀 Quick Start +1. **Clone & Inspect** + ```bash + git clone + cd TSYSDevStack + tree -L 2 # optional: explore the stack layout + ``` +2. **Run the Support Stack Demo** + ```bash + cd SupportStack + ./output/code/TSYSDevStack-SupportStack-Demo-Control.sh start + ./output/code/TSYSDevStack-SupportStack-Demo-Control.sh test + ``` + > Uses Docker Compose bundles under `SupportStack/output/docker-compose/`. +3. **Enter the Toolbox Workspace** + ```bash + cd ToolboxStack/output/toolbox-base + ./build.sh && ./run.sh up + docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh + ``` + +--- + +## 🧭 Working Agreement +- **Stacks stay in sync.** When you add or modify automation, update both the relevant stack README and any linked prompts/docs. +- **Collab vs Output.** Use `collab/` for planning and prompts, keep runnable artifacts under `output/`. +- **Document forward.** New workflows should land alongside tests and a short entry in the appropriate README table. + +--- + +## 📄 License +See [LICENSE](LICENSE) for full terms. Contributions are welcome—open a discussion in the relevant stack’s `collab/` area to kick things off. diff --git a/SupportStack/README.md b/SupportStack/README.md new file mode 100644 index 0000000..8f881d7 --- /dev/null +++ b/SupportStack/README.md @@ -0,0 +1,37 @@ +# 🛟 SupportStack + +The SupportStack delivers a curated demo environment for customer support tooling. It bundles Dockerized services, environment settings, automation scripts, and a growing library of collaboration notes. + +--- + +## Stack Snapshot +| Component | Purpose | Path | +|-----------|---------|------| +| Control Script | Orchestrates start/stop/update/test flows for the demo stack. | [`output/code/TSYSDevStack-SupportStack-Demo-Control.sh`](output/code/TSYSDevStack-SupportStack-Demo-Control.sh) | +| Environment Settings | Centralized `.env` style configuration consumed by scripts and compose files. | [`output/TSYSDevStack-SupportStack-Demo-Settings`](output/TSYSDevStack-SupportStack-Demo-Settings) | +| Docker Compose Bundles | Service definitions for docker-socket-proxy, homepage, WakaAPI, and MailHog. | [`output/docker-compose/`](output/docker-compose) | +| Service Config | Homepage/WakaAPI configuration mounted into containers. | [`output/config/`](output/config) | +| Tests | Shell-based smoke, unit, and discovery tests for stack services. | [`output/tests/`](output/tests) | +| Docs & Vendor Research | Reference material and curated vendor lists. | [`output/docs/`](output/docs) | +| Collaboration Notes | Product direction, prompts, and status updates. | [`collab/`](collab) | + +--- + +## Getting Started +1. Export or edit variables in `output/TSYSDevStack-SupportStack-Demo-Settings`. +2. Use the control script to manage the stack: + ```bash + ./output/code/TSYSDevStack-SupportStack-Demo-Control.sh start + ./output/code/TSYSDevStack-SupportStack-Demo-Control.sh test + ./output/code/TSYSDevStack-SupportStack-Demo-Control.sh stop + ``` +3. Review `output/tests/` for additional validation scripts. + +> ℹ️ The stack expects Docker access and creates the shared network `tsysdevstack-supportstack-demo-network` if it does not exist. + +--- + +## Collaboration Notes +- Keep demo automation in `output/` and exploratory material in `collab/`. +- When adding a new service, update both the compose files and the test suite to maintain coverage. +- Synchronize documentation changes with any updates to automation or configuration—future contributors rely on the README table as the source of truth. diff --git a/ToolboxStack/README.md b/ToolboxStack/README.md new file mode 100644 index 0000000..e264516 --- /dev/null +++ b/ToolboxStack/README.md @@ -0,0 +1,32 @@ +# 🧰 ToolboxStack + +ToolboxStack provides reproducible developer workspaces for TSYSDevStack contributors. The current `toolbox-base` image captures the daily-driver container environment used across the project. + +--- + +## Contents +| Area | Description | Path | +|------|-------------|------| +| Dev Container Image | Ubuntu 24.04 base with shell tooling, mise, aqua-managed CLIs, and Docker socket access. | [`output/toolbox-base/Dockerfile`](output/toolbox-base/Dockerfile) | +| Build Helpers | Wrapper scripts for building (`build.sh`) and running (`run.sh`) the Compose service. | [`output/toolbox-base/`](output/toolbox-base) | +| Devcontainer Config | VS Code Remote Container definition referencing the Compose service. | [`output/toolbox-base/.devcontainer/devcontainer.json`](output/toolbox-base/.devcontainer/devcontainer.json) | +| Prompt & Docs | Onboarding prompt plus a feature-rich README for future collaborators. | [`output/toolbox-base/PROMPT`](output/toolbox-base/PROMPT), [`output/toolbox-base/README.md`](output/toolbox-base/README.md) | +| Collaboration Notes | Shared design prompts and coordination notes for toolbox evolution. | [`collab/`](collab) | + +--- + +## Quick Start +```bash +cd output/toolbox-base +./build.sh # build the image with UID/GID matching your host +./run.sh up # launch the toolbox-base service in the background +docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh +``` +Use `./run.sh down` to stop the container when you are finished. + +--- + +## Contribution Tips +- Document every tooling change in both the `PROMPT` and `README.md`. +- Prefer installing CLIs via `aqua` and language runtimes via `mise` to keep the environment reproducible. +- Keep cache directories (`.build-cache/`, mise mounts) out of Git—they are already covered by the repo’s `.gitignore`.