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).
This commit is contained in:
TSYSDevStack Team
399
SupportStack/demo/README.md
Normal file
399
SupportStack/demo/README.md
Normal file
@@ -0,0 +1,399 @@
|
||||
<div align="center">
|
||||
|
||||
# 🚀 TSYS Developer Support Stack
|
||||
|
||||
[](https://www.docker.com/)
|
||||
[](https://gethomepage.dev/)
|
||||
[](https://wakapi.dev/)
|
||||
[](https://archivebox.io/)
|
||||
[](https://github.com/mailhog/MailHog)
|
||||
|
||||
> **A comprehensive developer support services stack with automatic service discovery**
|
||||
|
||||
---
|
||||
|
||||
</div>
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
- [🌟 Overview](#-overview)
|
||||
- [🏗️ Architecture](#️-architecture)
|
||||
- [⚡ Quick Start](#-quick-start)
|
||||
- [🔧 Services](#-services)
|
||||
- [📊 Service Access](#-service-access)
|
||||
- [🛠️ Configuration](#️-configuration)
|
||||
- [🔍 Health Checks](#-health-checks)
|
||||
- [📝 Development](#-development)
|
||||
- [🚨 Important Notes](#-important-notes)
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Overview
|
||||
|
||||
The TSYS Developer Support Stack provides a comprehensive suite of developer tools designed to enhance productivity and streamline development workflows. This demo-ready stack includes:
|
||||
|
||||
- **🏠 Homepage** - A beautiful, customizable dashboard with automatic service discovery
|
||||
- **⏱️ Wakapi** - Self-hosted time tracking for developers
|
||||
- **🗄️ ArchiveBox** - Web archiving solution for saving web content
|
||||
- **📧 MailHog** - Email testing service for development
|
||||
- **🐳 Docker Socket Proxy** - Secure Docker API access
|
||||
- **🗄️ PostgreSQL** - Reliable database backend (ready for additional services)
|
||||
- **🛡️ Pi-hole** - DNS-based ad blocking and network monitoring
|
||||
- **📊 Portainer** - Web-based Docker container management
|
||||
- **📈 InfluxDB** - Time series database for metrics storage
|
||||
- **📊 Grafana** - Analytics and visualization platform
|
||||
- **🎨 Draw.io** - Web-based diagramming and flowchart application
|
||||
- **📐 Kroki** - Service for converting text diagrams to images
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "TSYS Developer Support Stack"
|
||||
A[Homepage Dashboard<br/>Port: 4000]
|
||||
C[Wakapi Time Tracking<br/>Port: 4002]
|
||||
D[ArchiveBox<br/>Port: 4003]
|
||||
F[MailHog<br/>Port: 4005]
|
||||
G[Docker Socket Proxy<br/>Port: 2375]
|
||||
H[PostgreSQL<br/>Internal]
|
||||
I[Pi-hole<br/>Port: 4006]
|
||||
J[Portainer<br/>Port: 4007]
|
||||
K[InfluxDB<br/>Port: 4008]
|
||||
L[Grafana<br/>Port: 4009]
|
||||
M[Draw.io<br/>Port: 4010]
|
||||
N[Kroki<br/>Port: 4011]
|
||||
end
|
||||
|
||||
A --> C
|
||||
A --> D
|
||||
A --> F
|
||||
A --> G
|
||||
A --> I
|
||||
A --> J
|
||||
A --> K
|
||||
A --> L
|
||||
A --> M
|
||||
A --> N
|
||||
|
||||
subgraph "External Access"
|
||||
O[Developer Browser<br/>192.168.3.6]
|
||||
end
|
||||
|
||||
O --> A
|
||||
O --> C
|
||||
O --> D
|
||||
O --> F
|
||||
O --> I
|
||||
O --> J
|
||||
O --> K
|
||||
O --> L
|
||||
O --> M
|
||||
O --> N
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Quick Start
|
||||
|
||||
### 🎯 Prerequisites
|
||||
|
||||
- [Docker](https://www.docker.com/) 20.10+
|
||||
- [Docker Compose](https://docs.docker.com/compose/) 2.0+
|
||||
- Git
|
||||
|
||||
### 🚀 One-Command Deployment
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd TSYSDevStack/Support
|
||||
|
||||
# Start all services
|
||||
docker compose -f docker-compose-simple.yml up -d
|
||||
|
||||
# Wait for services to be healthy (optional)
|
||||
docker compose -f docker-compose-simple.yml ps
|
||||
```
|
||||
|
||||
That's it! 🎉 All services will be available within 60 seconds.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Services
|
||||
|
||||
| Service | Description | Port | Health Check | Status |
|
||||
|---------|-------------|------|--------------|--------|
|
||||
| **Homepage** | Developer dashboard with service discovery | `4000` | ✅ HTTP Check | 🟢 Active |
|
||||
| **Atuin** | Synced shell history database | `4001` | ✅ HTTP Check | 🟢 Active |
|
||||
| **Wakapi** | Time tracking for developers | `4002` | ✅ HTTP Check | 🟢 Active |
|
||||
| **ArchiveBox** | Web archiving solution | `4003` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **Tube Archivist** | YouTube media archiving | `4004` | ✅ HTTP Check | 🟡 Starting |
|
||||
| | **MailHog** | Email testing service | `4005` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **Docker Socket Proxy** | Secure Docker API access | `2375` | ✅ HTTP Check | 🟡 Starting |
|
||||
| | **PostgreSQL** | Database for Atuin | `5432` | ✅ DB Check | 🟢 Active |
|
||||
| | **Elasticsearch** | Search engine for Tube Archivist | `9200` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **Pi-hole** | DNS management and network monitoring | `4006` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **Portainer** | Web-based Docker container management | `4007` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **InfluxDB** | Time series database for metrics | `4008` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **Grafana** | Analytics and visualization platform | `4009` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **Draw.io** | Web-based diagramming application | `4010` | ✅ HTTP Check | 🟢 Active |
|
||||
| | **Kroki** | Diagrams as a service | `4011` | ✅ HTTP Check | 🟢 Active |
|
||||
|
||||
---
|
||||
|
||||
## 📊 Service Access
|
||||
|
||||
### 🏠 Homepage Dashboard
|
||||
```
|
||||
http://192.168.3.6:4000
|
||||
```
|
||||
- **Features**: Service discovery, system monitoring, quick links
|
||||
- **Auto-discovery**: All services automatically detected via Docker labels
|
||||
- **Widgets**: Resource monitoring, search, datetime
|
||||
|
||||
|
||||
|
||||
### ⏱️ Wakapi Time Tracking
|
||||
```
|
||||
http://192.168.3.6:4002
|
||||
```
|
||||
|
||||
### 🗄️ ArchiveBox Web Archiving
|
||||
```
|
||||
http://192.168.3.6:4003
|
||||
```
|
||||
- **Features**: Save web pages, full-text search, tag organization
|
||||
- **Demo Mode**: Open access for testing web archiving
|
||||
- **Storage**: File-based archive with SQLite metadata
|
||||
|
||||
|
||||
|
||||
### 📧 MailHog Email Testing
|
||||
```
|
||||
http://192.168.3.6:4005
|
||||
```
|
||||
- **Features**: Web interface for email testing, SMTP capture
|
||||
- **SMTP Port**: 1025 for application testing
|
||||
- **Demo**: Open access for email development
|
||||
|
||||
### 🛡️ Pi-hole DNS Management
|
||||
```
|
||||
http://192.168.3.6:4006/admin/index.php
|
||||
```
|
||||
- **Features**: DNS-based ad blocking and network monitoring
|
||||
- **Demo Credentials**: admin / demo_password
|
||||
- **DNS Ports**: 53 (TCP/UDP) for DNS resolution
|
||||
|
||||
### 📊 Portainer Container Management
|
||||
```
|
||||
http://192.168.3.6:4007
|
||||
```
|
||||
- **Features**: Web-based Docker container management
|
||||
- **Demo Credentials**: admin / demo_password
|
||||
- **Capabilities**: Container lifecycle, image management, volumes
|
||||
|
||||
### 📈 InfluxDB Time Series Database
|
||||
```
|
||||
http://192.168.3.6:4008
|
||||
```
|
||||
- **Features**: High-performance time series data storage
|
||||
- **Demo Credentials**: admin / demo_password
|
||||
- **Organization**: tsysdemo, Bucket: demo_metrics
|
||||
|
||||
### 📊 Grafana Analytics Platform
|
||||
```
|
||||
http://192.168.3.6:4009
|
||||
```
|
||||
- **Features**: Analytics and visualization for time series data
|
||||
- **Demo Credentials**: admin / demo_password
|
||||
- **Data Source**: Pre-configured InfluxDB connection
|
||||
|
||||
### 🎨 Draw.io Diagramming
|
||||
```
|
||||
http://192.168.3.6:4010
|
||||
```
|
||||
- **Features**: Web-based diagramming and flowchart creation
|
||||
- **Export Options**: PNG, SVG, PDF, and more
|
||||
- **Demo Mode**: No authentication required
|
||||
|
||||
### 📐 Kroki Diagrams as a Service
|
||||
```
|
||||
http://192.168.3.6:4011
|
||||
```
|
||||
- **Features**: Convert text diagrams to images
|
||||
- **Supported Formats**: PlantUML, Mermaid, GraphViz, and more
|
||||
- **API**: RESTful interface for diagram generation
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Configuration
|
||||
|
||||
### 📁 Directory Structure
|
||||
|
||||
```
|
||||
Support/
|
||||
├── docker-compose-simple.yml # Simplified orchestration file
|
||||
├── demo.env # Environment configuration file (rename from demo.env if needed)
|
||||
├── start-stack.sh # Startup script
|
||||
├── test-stack.sh # Test suite
|
||||
├── homepage/
|
||||
│ └── config/
|
||||
│ ├── settings.yaml # Homepage configuration
|
||||
│ ├── docker.yaml # Docker integration
|
||||
│ └── bookmarks.yaml # Quick links
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
### 🧪 Environment Configuration
|
||||
|
||||
The stack uses the `demo.env` file for configuration. To customize settings:
|
||||
|
||||
1. Review the default settings in `demo.env`
|
||||
2. Make changes as needed (especially PUID, PGID, and passwords)
|
||||
3. The startup scripts will use this file directly
|
||||
|
||||
### 🔐 Demo Credentials
|
||||
|
||||
> ⚠️ **WARNING**: These are demo credentials only. Do not use in production!
|
||||
|
||||
| Service | Username | Password | Database |
|
||||
|---------|----------|----------|----------|
|
||||
| PostgreSQL | `atuin` | `demo_password` | `atuin` |
|
||||
| Pi-hole | `admin` | `demo_password` | - |
|
||||
| Portainer | `admin` | `demo_password` | - |
|
||||
| InfluxDB | `admin` | `demo_password` | tsysdemo/demo_metrics |
|
||||
| Grafana | `admin` | `demo_password` | - |
|
||||
| Wakapi | - | - | SQLite |
|
||||
| ArchiveBox | - | - | SQLite |
|
||||
| Draw.io | - | - | - |
|
||||
| Kroki | - | - | - |
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Health Checks
|
||||
|
||||
All services include comprehensive health checks:
|
||||
|
||||
### 📊 Check Service Status
|
||||
```bash
|
||||
# View all services and their health
|
||||
docker-compose ps
|
||||
|
||||
# Check logs for any service
|
||||
docker-compose logs <service-name>
|
||||
|
||||
# Monitor health in real-time
|
||||
watch docker-compose ps
|
||||
```
|
||||
|
||||
### 🩺 Health Check Details
|
||||
|
||||
| Service | Check Type | Interval | Timeout | Retries |
|
||||
|---------|------------|----------|---------|---------|
|
||||
| Homepage | HTTP GET `/` | 30s | 10s | 3 |
|
||||
| Wakapi | HTTP GET `/` | 30s | 10s | 3 |
|
||||
| ArchiveBox | HTTP GET `/` | 30s | 10s | 3 |
|
||||
| MailHog | HTTP GET `/` | 30s | 10s | 3 |
|
||||
| Pi-hole | HTTP GET `/admin/index.php` | 30s | 10s | 3 |
|
||||
| Portainer | HTTP GET `/` | 30s | 10s | 3 |
|
||||
| InfluxDB | HTTP GET `/ping` | 30s | 10s | 3 |
|
||||
| Grafana | HTTP GET `/api/health` | 30s | 10s | 3 |
|
||||
| Draw.io | HTTP GET `/` | 30s | 10s | 3 |
|
||||
| Kroki | HTTP GET `/health` | 30s | 10s | 3 |
|
||||
| Docker Socket Proxy | HTTP GET `/` | 30s | 10s | 3 |
|
||||
| PostgreSQL | `pg_isready` | 30s | 10s | 3 |
|
||||
|
||||
---
|
||||
|
||||
## 📝 Development
|
||||
|
||||
### 🔧 Customization
|
||||
|
||||
#### Adding New Services
|
||||
1. Add service to `docker-compose.yml`
|
||||
2. Add Homepage labels for auto-discovery
|
||||
3. Update `homepage/config/docker.yaml`
|
||||
4. Include health checks
|
||||
|
||||
#### Modifying Homepage
|
||||
Edit files in `homepage/config/`:
|
||||
- `settings.yaml` - Main configuration
|
||||
- `docker.yaml` - Container monitoring
|
||||
- `bookmarks.yaml` - Quick links
|
||||
|
||||
### 🔄 Common Commands
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker compose -f docker-compose-simple.yml up -d
|
||||
|
||||
# Stop all services
|
||||
docker compose -f docker-compose-simple.yml down
|
||||
|
||||
# View logs
|
||||
docker compose -f docker-compose-simple.yml logs -f
|
||||
|
||||
# Rebuild services
|
||||
docker compose -f docker-compose-simple.yml up -d --build
|
||||
|
||||
# Clean up volumes (⚠️ destroys data)
|
||||
docker compose -f docker-compose-simple.yml down -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Important Notes
|
||||
|
||||
### ⚠️ Demo Environment
|
||||
|
||||
- **Purpose**: Demonstration and testing only
|
||||
- **Data Persistence**: None! All data is stored in ephemeral Docker volumes that are destroyed when the stack is removed
|
||||
- **Security**: Hardcoded credentials, no encryption, bind mounts removed for security
|
||||
- **Network**: All services exposed to localhost only
|
||||
|
||||
### 🔒 Production Considerations
|
||||
|
||||
For production deployment, consider:
|
||||
- 🔐 Secure credential management
|
||||
- 🔒 HTTPS/TLS encryption
|
||||
- 🛡️ Network isolation
|
||||
- 💾 Persistent storage solutions
|
||||
- 📊 Monitoring and alerting
|
||||
- 🔄 High availability
|
||||
- 🗂️ Backup strategies for important data
|
||||
|
||||
### 🐛 Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Services not starting | Check Docker daemon, verify ports |
|
||||
| Health checks failing | Review logs, check resource availability |
|
||||
| Cannot access services | Verify firewall, check port binding |
|
||||
| Data not persisting | Ensure volumes are properly mounted |
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For issues and questions:
|
||||
|
||||
1. Check service logs: `docker-compose logs <service>`
|
||||
2. Verify health status: `docker-compose ps`
|
||||
3. Review configuration files
|
||||
4. Check port availability
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🎉 Happy Developing! 🎉**
|
||||
|
||||
*Built with ❤️ for the TSYS Development Team*
|
||||
|
||||
---
|
||||
|
||||
[](https://github.com/your-org/TSYSDevStack)
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user