KNEL/TSYSDevStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1f6fd609e6c9f3b464e1cd1671fb9a56baf724f3
TSYSDevStack/SupportStack/demo/PRD.md
TSYSDevStack Team 0785722981 feat: 🚀 Initialize TSYS Developer Support Stack demo environment 
- Add comprehensive Docker Compose configuration with 16 developer services
- Configure Homepage dashboard with service discovery and grouping
- Set up environment configuration for demo deployment
- Include project documentation (PRD, README, User Guide, Agent guidelines)
- Establish foundation for developer tooling stack with proper networking and security

Services include developer tools (Homepage, Atuin, Wakapi, ArchiveBox, Tube Archivist, MailHog),
infrastructure (PostgreSQL, Elasticsearch, Redis, Docker Socket Proxy),
monitoring (InfluxDB, Grafana), and documentation (Draw.io, Kroki).
2025-11-13 17:35:34 -05:00

365 lines
11 KiB
Markdown
Raw Blame History

# TSYS Developer Support Stack - Product Requirements Document (Demo Version)
## 📋 Document Overview
**Document ID**: PRD-SUPPORT-DEMO-001
**Version**: 1.0
**Date**: 2025-11-13
**Author**: TSYS Development Team
**Status**: Draft
---
## 🎯 Product Vision
To create a comprehensive, demo-ready developer support services stack that enhances developer productivity and quality of life for the TSYS engineering team. This stack is designed to run locally on every developer workstation, providing essential services for inner loop development workflows while maintaining security, simplicity, and adherence to free/libre/open source principles.
---
## 🏗️ Architecture Overview
### Design Principles
1. **Demo-First**: All services configured for easy demonstration with no persistent data, hardcoded credentials, and minimal setup complexity
2. **Service Discovery**: Automatic service discovery via Homepage dashboard with Docker labels
3. **FOSS Only**: Exclusively use free/libre/open source software
4. **Inner Loop Focus**: Support daily development workflows, not project-specific dependencies
5. **Workstation Local**: Run locally on developer machines, not centralized infrastructure
6. **Security Conscious**: Demo-hardened configurations with clear separation from production
### Service Categories
- **Infrastructure Services**: Core platform services (Pi-hole, Portainer)
- **Monitoring & Observability**: Metrics and visualization (InfluxDB, Grafana)
- **Documentation & Diagramming**: Knowledge management tools (Draw.io, Kroki)
- **Developer Tools**: Productivity and workflow enhancers
---
## 📊 Functional Requirements
### FR-001: Infrastructure Services
#### FR-001.1: Pi-hole DNS Management
- **Description**: DNS-based ad blocking and network monitoring
- **Requirements**:
- Web-based administration interface
- DNS filtering capabilities
- Network traffic monitoring
- Demo configuration with default settings
- Port assignment: 4006
- Health check endpoint: HTTP GET /
- Homepage integration with Infrastructure group
#### FR-001.2: Portainer Container Management
- **Description**: Web-based Docker container management interface
- **Requirements**:
- Container lifecycle management (start/stop/restart)
- Image management and registry integration
- Volume and network management
- User authentication (demo credentials)
- Port assignment: 4007
- Health check endpoint: HTTP GET /
- Homepage integration with Infrastructure group
### FR-002: Monitoring & Observability
#### FR-002.1: InfluxDB Time Series Database
- **Description**: High-performance time series database for metrics storage
- **Requirements**:
- HTTP API for data ingestion and querying
- Web-based administration interface
- Demo database with sample data
- Port assignment: 4008
- Health check endpoint: HTTP GET /ping
- Homepage integration with Monitoring group
#### FR-002.2: Grafana Visualization Platform
- **Description**: Analytics and visualization platform for time series data
- **Requirements**:
- Pre-configured data source connection to InfluxDB
- Demo dashboards for system metrics
- Web-based dashboard creation and editing
- Admin credentials: admin/demo_password
- Port assignment: 4009
- Health check endpoint: HTTP GET /api/health
- Homepage integration with Monitoring group
### FR-003: Documentation & Diagramming
#### FR-003.1: Draw.io Diagramming Server
- **Description**: Web-based diagramming and flowchart application
- **Requirements**:
- Browser-based diagram creation and editing
- Export to multiple formats (PNG, SVG, PDF)
- Integration with cloud storage (optional)
- No authentication required (demo mode)
- Port assignment: 4010
- Health check endpoint: HTTP GET /
- Homepage integration with Documentation group
#### FR-003.2: Kroki Diagrams as a Service
- **Description**: Service for converting text diagrams to images
- **Requirements**:
- Support for multiple diagram types (PlantUML, Mermaid, GraphViz)
- HTTP API for diagram generation
- Simple web interface for testing
- No authentication required (demo mode)
- Port assignment: 4011
- Health check endpoint: HTTP GET /health
- Homepage integration with Documentation group
---
## 🔧 Technical Requirements
### TR-001: Docker Integration
- All services must be containerized using official Docker images
- Services must use consistent naming convention: `tsysdevstack-supportstack-{service}`
- All services must include comprehensive health checks
- Services must include proper Homepage labels for auto-discovery
- Restart policy: `unless-stopped`
### TR-002: Network Configuration
- All services must use the `tsysdevstack_supportstack` network
- Port assignments must follow the 4000+ range pattern
- Services must be accessible via `192.168.3.6:{port}`
- Inter-service communication via container names
### TR-003: Data Management
- No persistent data storage (demo mode)
- Use Docker volumes for temporary data only
- All data must be reset on container restart
- Hardcoded demo credentials only
- No encryption or security hardening
### TR-004: Service Discovery
- All services must include Homepage labels:
- `homepage.group`: Service category
- `homepage.name`: Display name
- `homepage.icon`: Appropriate icon
- `homepage.href`: Full URL
- `homepage.description`: Brief service description
---
## 🎨 User Experience Requirements
### UX-001: Homepage Dashboard
- Single entry point for all services via Homepage at port 4000
- Automatic service discovery and organization
- Consistent visual design and navigation
- Real-time service status indicators
### UX-002: Service Accessibility
- All services accessible via web browser
- No complex setup or configuration required
- Default credentials where authentication is needed
- Clear error messages and troubleshooting guidance
### UX-003: Demo Experience
- One-command deployment: `docker compose up -d`
- Services ready within 60 seconds
- All features immediately accessible
- No data persistence between sessions
---
## 🔒 Security Requirements
### SEC-001: Demo Security Model
- All services configured for demo/development use only
- Hardcoded credentials clearly marked as demo-only
- No external network access except for image pulls
- No encryption or security hardening
### SEC-002: Network Isolation
- Services isolated within Docker network
- Only necessary ports exposed to host
- No inter-container privilege escalation
- Docker socket proxy for secure API access
---
## 📋 Non-Functional Requirements
### NFR-001: Performance
- All services must start within 60 seconds
- Health checks must complete within 10 seconds
- Memory usage per service: < 512MB (where applicable)
- CPU usage: < 25% per service (idle)
### NFR-002: Reliability
- All services must include health checks
- Automatic restart on failure
- Graceful shutdown handling
- Dependency management between services
### NFR-003: Maintainability
- Clear, commented Docker Compose configuration
- Consistent service naming and organization
- Comprehensive documentation
- Easy service addition/removal
---
## 🧪 Testing Requirements
### TST-001: Automated Testing
- Comprehensive test suite (`test-stack.sh`)
- Service health validation
- Port accessibility verification
- Service discovery functionality
- Resource usage monitoring
### TST-002: Manual Testing
- All web interfaces accessible and functional
- Demo credentials work correctly
- Service integration testing
- User workflow validation
---
## 📚 Documentation Requirements
### DOC-001: Technical Documentation
- Updated README.md with all services
- Service access information
- Configuration details
- Troubleshooting guide
### DOC-002: User Documentation
- Quick start guide
- Service descriptions and use cases
- Demo credentials reference
- FAQ section
---
## ✅ Acceptance Criteria
### AC-001: Deployment Success
- [ ] All services start successfully with `docker compose up -d`
- [ ] All services pass health checks within 60 seconds
- [ ] Homepage discovers and displays all services
- [ ] All web interfaces accessible via browser
### AC-002: Functionality Verification
- [ ] Pi-hole web interface loads and functions
- [ ] Portainer manages containers correctly
- [ ] InfluxDB accepts data and responds to queries
- [ ] Grafana connects to InfluxDB and displays dashboards
- [ ] Draw.io creates and exports diagrams
- [ ] Kroki generates diagrams from text
### AC-003: Integration Testing
- [ ] Service discovery works correctly
- [ ] Inter-service communication functions
- [ ] Health checks trigger appropriately
- [ ] Resource usage remains within limits
---
## 🚀 Success Metrics
### Deployment Metrics
- Time to full stack readiness: < 2 minutes
- Service success rate: 100%
- Health check pass rate: 100%
### User Experience Metrics
- Single-command deployment success
- All services accessible via Homepage
- No configuration required for basic use
---
## 📅 Implementation Timeline
### Phase 1: Core Infrastructure (Week 1)
- Pi-hole implementation
- Portainer integration
- Basic service discovery validation
### Phase 2: Monitoring Stack (Week 1)
- InfluxDB deployment
- Grafana configuration
- Dashboard creation
### Phase 3: Documentation Tools (Week 2)
- Draw.io server setup
- Kroki service implementation
- Integration testing
### Phase 4: Testing & Documentation (Week 2)
- Comprehensive test suite
- Documentation updates
- Final validation
---
## 🔄 Change Management
### Version Control
- All changes tracked via Git
- Conventional commit messages
- Atomic commits with clear descriptions
### Quality Assurance
- Automated testing on all changes
- Manual validation of new services
- Documentation updates with each change
---
## 📞 Support & Maintenance
### Troubleshooting
- Service logs accessible via `docker compose logs`
- Health check status via `docker compose ps`
- Common issues documented in README
### Updates
- Regular image updates via Docker Hub
- Configuration changes tracked in Git
- Backward compatibility maintained where possible
---
## 📋 Appendix
### A. Port Assignments
| Service | Port | Group |
|---------|------|-------|
| Homepage | 4000 | Developer Tools |
| Atuin | 4001 | Developer Tools |
| Wakapi | 4002 | Developer Tools |
| ArchiveBox | 4003 | Developer Tools |
| Tube Archivist | 4004 | Developer Tools |
| MailHog | 4005 | Developer Tools |
| Pi-hole | 4006 | Infrastructure |
| Portainer | 4007 | Infrastructure |
| InfluxDB | 4008 | Monitoring |
| Grafana | 4009 | Monitoring |
| Draw.io | 4010 | Documentation |
| Kroki | 4011 | Documentation |
### B. Demo Credentials
| Service | Username | Password |
|---------|----------|----------|
| Grafana | admin | demo_password |
| Portainer | admin | demo_password |
### C. Service Dependencies
- Pi-hole: No dependencies
- Portainer: Docker Socket Proxy
- InfluxDB: No dependencies
- Grafana: InfluxDB
- Draw.io: No dependencies
- Kroki: No dependencies
---
**Document End**
*This PRD serves as the source of truth for the TSYS Developer Support Stack demo implementation and will be used for audit and quality assurance purposes.*
Reference in New Issue View Git Blame Copy Permalink