TSYSDevStack/SupportStack/demo

🚀 TSYS Developer Support Stack

A comprehensive developer support services stack with automatic service discovery

---

📋 Table of Contents

• 🌟 Overview
• 🏗️ Architecture
• ⚡ Quick Start
• 🔧 Services
• 📊 Service Access
• 🛠️ Configuration
• 🔍 Health Checks
• 📝 Development
• 🚨 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

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 20.10+
• Docker Compose 2.0+
• Git

🚀 One-Command Deployment

# 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
	MailHog	Email testing service	4005	✅ HTTP Check
	Docker Socket Proxy	Secure Docker API access	2375	✅ HTTP Check
	PostgreSQL	Database for Atuin	5432	✅ DB Check
	Elasticsearch	Search engine for Tube Archivist	9200	✅ HTTP Check
	Pi-hole	DNS management and network monitoring	4006	✅ HTTP Check
	Portainer	Web-based Docker container management	4007	✅ HTTP Check
	InfluxDB	Time series database for metrics	4008	✅ HTTP Check
	Grafana	Analytics and visualization platform	4009	✅ HTTP Check
	Draw.io	Web-based diagramming application	4010	✅ HTTP Check
	Kroki	Diagrams as a service	4011	✅ HTTP Check

---

📊 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

# 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

# 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

---

🎉 Happy Developing! 🎉

Built with ❤️ for the TSYS Development Team

---