KNEL/TSYSDevStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

snapshot

Browse Source
This commit is contained in:
Charles N Wyble - admin
2025-10-28 19:57:51 -05:00
parent 9f17603c1e
commit 65b278e33f
27 changed files with 875 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
collab/SupportStack/BuildTheStack
View File

@@ -7,13 +7,21 @@ Create an out-of-the-box, localhost-bound only, ephemeral Docker volume-only dem
Create a proof of concept with docker-socket-proxy, homepage, and wakaapi components that demonstrate proper homepage integration via Docker Compose labels. This MVP will serve as a validation of the full approach before proceeding with the complete stack implementation.
## Architecture Requirements
- All Docker artifacts must be prefixed with `TSYSDevStack-SupportStack-Demo`
- All Docker artifacts must be prefixed with `tsysdevstack-supportstack-demo-`
- This includes containers, networks, volumes, and any other Docker artifacts
- Example: `tsysdevstack-supportstack-demo-homepage`, `tsysdevstack-supportstack-demo-network`, etc.
- Run exclusively on localhost (localhost binding only)
- Ephemeral volumes only (no persistent storage)
- Resource limits set for single-user demo capacity
- No external network access (localhost bound only)
- Components: docker-socket-proxy, portainer, homepage as foundational elements
- All artifacts must go into artifacts/SupportStack directory to keep the directory well organized and avoid cluttering the root directory
- Homepage container needs direct access to Docker socket for labels to auto-populate (not through proxy)
- Docker socket proxy is for other containers that need Docker access but don't require direct socket access
- Portainer can use docker-socket-proxy for read-only access, but homepage needs direct socket access
- All containers need proper UID/GID mapping for security
- Docker group GID must be mapped properly for containers using Docker socket
- Non-Docker socket using containers should use invoking UID/GID
## Development Methodology
- Strict Test Driven Development (TDD) process
@@ -29,13 +37,16 @@ Create a proof of concept with docker-socket-proxy, homepage, and wakaapi compon
## MVP Component Development Sequence (Test Run)
1. **MVP**: docker-socket-proxy, homepage, wakaapi (each must fully satisfy Definition of Done before proceeding)
- docker-socket-proxy: Enable Docker socket access for homepage integration
- homepage: Configure to access Docker socket and discover labeled containers
- docker-socket-proxy: Enable Docker socket access for containers that need it (not homepage)
- homepage: Configure to access Docker socket directly for automatic label discovery
- wakaapi: Integrate with homepage using proper labels
- All services must utilize Docker Compose labels to automatically show up in homepage
- Implement proper service discovery for homepage integration using gethomepage labels
- Ensure all components are properly labeled with homepage integration labels
- Implement proper startup ordering using depends_on with health checks
- Homepage container requires direct Docker socket access for automatic service discovery
- Docker socket proxy provides controlled access for other containers
- All containers must have proper UID/GID mapping for security
## Component Completion Validation
- Each component must pass health checks for 5 consecutive minutes before moving to the next
@@ -45,7 +56,7 @@ Create a proof of concept with docker-socket-proxy, homepage, and wakaapi compon
- Homepage must automatically detect and display all services with proper labels
- Specific validation checkpoints after each service deployment:
- docker-socket-proxy: Validate Docker socket access and network connectivity to Docker daemon
- homepage: Validate homepage starts and can connect to Docker socket proxy, verify UI is accessible
- homepage: Validate homepage starts and can connect to Docker socket directly, verify UI is accessible
- wakaapi: Validate service starts and can be integrated into homepage with proper labels
- Each service must be validated in homepage dashboard after integration
- Detailed homepage integration validation steps:
@@ -54,6 +65,9 @@ Create a proof of concept with docker-socket-proxy, homepage, and wakaapi compon
- Validate service URL in homepage correctly links to the service
- Verify service group assignment in homepage is correct
- Check that any configured widgets appear properly in homepage
- Homepage must automatically discover services via Docker labels without manual configuration
- Validate Docker socket connectivity for automatic service discovery
- Confirm homepage can access and display service status information
- Update STATUS.md with validation results for each component
## Technical Specifications
@@ -72,9 +86,9 @@ Create a proof of concept with docker-socket-proxy, homepage, and wakaapi compon
- docker-socket-proxy: Internal network only, no external ports exposed
- homepage: Port 4000 (localhost only) - configurable via environment variable
- wakaapi: Port 4001 (localhost only) - configurable via environment variable
- All environment variables must be pre-set in TSYSDevStack-SupportStack-Demo-Settings file (single settings file for simplicity in demo)
- All docker compose files (one per component) should be prefixed with: TSYSDevStack-SupportStack-Demo-DockerCompose-
- All docker compose files should use environment variables for everything (variables will be set in TSYSDevStack-SupportStack-Demo-Settings file)
- All environment variables must be pre-set in tsysdevstack-supportstack-demo-Settings file (single settings file for simplicity in demo)
- All docker compose files (one per component) should be prefixed with: tsysdevstack-supportstack-demo-DockerCompose-
- All docker compose files should use environment variables for everything (variables will be set in tsysdevstack-supportstack-demo-Settings file)
- Health checks must validate service readiness before proceeding with dependent components
- Health check endpoints must be accessible only from internal network
- Health check configurations must be parameterized via environment variables
@@ -89,11 +103,20 @@ Create a proof of concept with docker-socket-proxy, homepage, and wakaapi compon
- Implement security scanning during build process (for demo, secrets via environment variables are acceptable)
- Define network policies for internal communication only
- Use depends_on with health checks to ensure proper startup ordering of services
- Homepage container requires direct Docker socket access (not through proxy) for automatic label discovery
- Docker socket proxy provides controlled access for other containers that need Docker access
- Portainer can use docker-socket-proxy for read-only access
- All containers must have proper UID/GID mapping for security
- Docker group GID must be mapped for containers using Docker socket
- Homepage container must have Docker socket access for labels to auto-populate
## Stack Control
- All control of the stack should go into a script called TSYSDevStack-SupportStack-Demo-Control.sh
- All control of the stack should go into a script called tsysdevstack-supportstack-demo-Control.sh
- The script should take the following arguments: start/stop/uninstall/update/test
- Ensure script is executable and contains error handling
- Script must handle UID/GID mapping for non-Docker socket using containers
- Script must map host Docker GID to containers using Docker socket
- Script should warn about Docker socket access requirements for homepage
## Component Definition of Done
- All health checks pass consistently for each component
@@ -116,6 +139,16 @@ Create a proof of concept with docker-socket-proxy, homepage, and wakaapi compon
- Component properly labeled with homepage integration labels (homepage.group, homepage.name, homepage.icon, etc.)
- Container uses pinned image tags rather than 'latest'
- Services validate properly in homepage after integration
- Homepage container has direct Docker socket access for automatic service discovery
- Homepage automatically discovers and displays services with proper labels
- Homepage validates Docker socket connectivity and service discovery
- All homepage integration labels are properly applied and validated
- Services appear in homepage with correct grouping, naming, and icons
- Homepage container has direct Docker socket access for automatic label discovery
- Docker socket proxy provides access for other containers that need Docker access
- Proper UID/GID mapping implemented for all containers
- Docker group GID properly mapped for containers using Docker socket
- All warnings addressed and resolved during implementation
## Testing Requirements
- Unit tests for each component configuration