From 55aa340a6c98254a422d6c16c42689dad5bf0130 Mon Sep 17 00:00:00 2001 From: reachableceo Date: Mon, 27 Apr 2026 13:07:02 -0500 Subject: [PATCH] docs(demo): synchronize all documentation with 16-service stack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix all documentation to match the actual running stack. Every service count, port number, credential, network name, container name, and dependency is now accurate across all files. Key changes: - Remove all stale Portainer/portainer references (replaced by Dockhand) - Fix project name from tsysdevstack to kneldevstack everywhere - Fix volume name pattern (underscore not dash after project name) - Fix network names (add -network suffix, correct subnet in commands) - Fix Homepage category from Infrastructure to Developer Tools - Add companion services (ta-redis, ta-elasticsearch) to all service lists - Fix Dockhand dependency description (direct socket, not proxy) - Remove port 4005 from all host-facing health check loops and port tables - Fix broken commands (docker exec dockhand docker version, wrong volume globs) - Fix INFLUXDB_ADMIN_USER credential references from demo_admin to admin - Fix Grafana datasource user to match - Fix misleading "ports 4000-4018" range to explicit port list - Add Docker Socket Proxy internal-only notes where applicable - Update root AGENTS.md service categories to match compose labels 💘 Generated with Crush Assisted-by: GLM-5.1 via Crush --- AGENTS.md | 38 ++++++++++++++++------------- demo/AGENTS.md | 10 ++++---- demo/README.md | 19 ++++++++------- demo/docs/api-docs/README.md | 10 ++++---- demo/docs/service-guides/README.md | 2 +- demo/docs/troubleshooting/README.md | 25 ++++++++++--------- 6 files changed, 55 insertions(+), 49 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index be61ae3..e75f3d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ This repository contains a Docker Compose-based multi-service stack that provide ### Project Type - **Infrastructure as Code**: Docker Compose with shell orchestration -- **Multi-Service Stack**: 13 services across 4 categories +- **Multi-Service Stack**: 16 services across 4 categories - **Demo-First Architecture**: All configurations for demonstration purposes only ### Directory Structure @@ -120,11 +120,10 @@ docker run --rm -v "$(pwd):/workdir" hadolint/hadolint ## Code Organization & Structure ### Service Categories -1. **Infrastructure Services** (ports 4000-4007) - - Homepage (4000) - Central dashboard for service discovery - - Docker Socket Proxy (4005) - Security layer for Docker API access +1. **Infrastructure Services** (ports 4005-4007) + - Docker Socket Proxy (4005) - Security layer for Docker API access (internal only) - Pi-hole (4006) - DNS management with ad blocking - - Portainer (4007) - Web-based container management + - Dockhand (4007) - Web-based container management 2. **Monitoring & Observability** (ports 4008-4009) - InfluxDB (4008) - Time series database for metrics @@ -134,14 +133,19 @@ docker run --rm -v "$(pwd):/workdir" hadolint/hadolint - Draw.io (4010) - Web-based diagramming application - Kroki (4011) - Diagrams as a service -4. **Developer Tools** (ports 4012, 4013, 4014, 4015, 4017, 4018) +4. **Developer Tools** (ports 4000, 4012-4018) + - Homepage (4000) - Central dashboard for service discovery - Atomic Tracker (4012) - Habit tracking and personal dashboard - ArchiveBox (4013) - Web archiving solution - - Tube Archivist (4014) - YouTube video archiving + - Tube Archivist (4014) - YouTube video archiving (requires ta-redis + ta-elasticsearch) - Wakapi (4015) - Open-source WakaTime alternative (time tracking) - MailHog (4017) - Web and API based SMTP testing - Atuin (4018) - Magical shell history synchronization +5. **Companion Services** (internal only, no host ports) + - ta-redis - Redis cache for Tube Archivist + - ta-elasticsearch - Elasticsearch index for Tube Archivist + ### Configuration Management - **Environment Variables**: All configuration via `demo/demo.env` - **Template-Based**: `docker-compose.yml` generated from `docker-compose.yml.template` using `envsubst` @@ -151,10 +155,10 @@ docker run --rm -v "$(pwd):/workdir" hadolint/hadolint ## Naming Conventions & Style Patterns ### Service Naming -- **Container Names**: `tsysdevstack-supportstack-demo-` -- **Volume Names**: `tsysdevstack-supportstack-demo-_data` -- **Network Name**: `tsysdevstack-supportstack-demo-network` -- **Project Name**: `tsysdevstack-supportstack-demo` +- **Container Names**: `kneldevstack-supportstack-demo-` +- **Volume Names**: `kneldevstack-supportstack-demo__data` +- **Network Name**: `kneldevstack-supportstack-demo-network` +- **Project Name**: `kneldevstack-supportstack-demo` ### Port Assignment - **Range**: 4000-4099 @@ -257,7 +261,7 @@ Before ANY file is created or modified: ### Volume vs Bind Mount Strategy - **Prefer Volumes**: Use Docker volumes for data storage - **Minimal Bind Mounts**: Use host bind mounts only for configuration that needs persistence -- **Dynamic Naming**: Volume names follow pattern: `tsysdevstack-supportstack-demo-_data` +- **Dynamic Naming**: Volume names follow pattern: `kneldevstack-supportstack-demo__data` - **Permission Mapping**: UID/GID mapped via environment variables ### Service Discovery Mechanism @@ -275,7 +279,7 @@ Before ANY file is created or modified: ## Project-Specific Context ### Current State -- **Demo Environment**: Fully configured with 13 services +- **Demo Environment**: Fully configured with 16 services - **Production Environment**: Placeholder only, not yet implemented - **Documentation**: Comprehensive (AGENTS.md, PRD.md, README.md) - **Scripts**: Complete orchestration and testing scripts available @@ -316,8 +320,8 @@ Before ANY file is created or modified: ### Required Variables ```bash -COMPOSE_PROJECT_NAME=tsysdevstack-supportstack-demo -COMPOSE_NETWORK_NAME=tsysdevstack-supportstack-demo-network +COMPOSE_PROJECT_NAME=kneldevstack-supportstack-demo +COMPOSE_NETWORK_NAME=kneldevstack-supportstack-demo-network # User Detection (Auto-populated by demo-stack.sh) DEMO_UID= @@ -328,7 +332,7 @@ DEMO_DOCKER_GID= HOMEPAGE_PORT=4000 DOCKER_SOCKET_PROXY_PORT=4005 PIHOLE_PORT=4006 -PORTAINER_PORT=4007 +DOCKHAND_PORT=4007 INFLUXDB_PORT=4008 GRAFANA_PORT=4009 DRAWIO_PORT=4010 @@ -365,7 +369,7 @@ DEMO_ADMIN_PASSWORD=demo_password 2. **Permission Issues**: Verify UID/GID in demo.env match current user 3. **Image Pull Failures**: Run `docker pull ` manually 4. **Health Check Failures**: Check service logs with `docker compose logs ` -5. **Network Issues**: Verify network exists: `docker network ls | grep tsysdevstack` +5. **Network Issues**: Verify network exists: `docker network ls | grep kneldevstack` ### Getting Help 1. Check troubleshooting section in demo/README.md diff --git a/demo/AGENTS.md b/demo/AGENTS.md index 96c063c..742b597 100644 --- a/demo/AGENTS.md +++ b/demo/AGENTS.md @@ -8,7 +8,7 @@ - **Dynamic User Handling**: Automatic UID/GID detection and application - **Security-First**: Docker socket proxy for all container operations - **Minimal Bind Mounts**: Prefer Docker volumes over host bind mounts. Use host bind mounts only for minimal bootstrap purposes of configuration data that needs to be persistent. -- **Consistent Naming**: `tsysdevstack-supportstack-demo-` prefix everywhere including in the docker-compose file for the service names. +- **Consistent Naming**: `kneldevstack-supportstack-demo-` prefix everywhere including in the docker-compose file for the service names. - **One-Command Deployment**: Single script deployment with full validation ### Dynamic Environment Strategy @@ -119,8 +119,8 @@ services: #### Dynamic Variable Requirements - **UID/GID**: Current user and group detection - **DOCKER_GID**: Docker group ID for socket access -- **COMPOSE_PROJECT_NAME**: `tsysdevstack-supportstack-demo` -- **COMPOSE_NETWORK_NAME**: `tsysdevstack-supportstack-demo-network` +- **COMPOSE_PROJECT_NAME**: `kneldevstack-supportstack-demo` +- **COMPOSE_NETWORK_NAME**: `kneldevstack-supportstack-demo-network` - **Service Ports**: All configurable via environment variables ### Port Assignment Strategy @@ -130,7 +130,7 @@ services: - Avoid conflicts with host services ### Network Configuration -- Network name: `tsysdevstack_supportstack-demo` +- Network name: `kneldevstack-supportstack-demo` - IP binding: `192.168.3.6:{port}` where applicable - Inter-service communication via container names - Only necessary ports exposed to host @@ -195,7 +195,7 @@ services: ### Template-Driven Development - **Variable Configuration**: All settings via environment variables -- **Naming Convention**: Consistent `tsysdevstack-supportstack-demo-` prefix +- **Naming Convention**: Consistent `kneldevstack-supportstack-demo-` prefix - **User Handling**: Dynamic UID/GID detection in all services - **Security Integration**: Docker socket proxy for container operations - **Volume Strategy**: Docker volumes with dynamic naming diff --git a/demo/README.md b/demo/README.md index d54ae6d..bbebb41 100644 --- a/demo/README.md +++ b/demo/README.md @@ -58,11 +58,11 @@ All configuration is managed through `demo.env` and dynamic detection: | Variable | Description | Default | |-----------|-------------|----------| -| **COMPOSE_PROJECT_NAME** | Consistent naming prefix | `tsysdevstack-supportstack-demo` | +| **COMPOSE_PROJECT_NAME** | Consistent naming prefix | `kneldevstack-supportstack-demo` | | **UID** | Current user ID | Auto-detected | | **GID** | Current group ID | Auto-detected | | **DOCKER_GID** | Docker group ID | Auto-detected | -| **COMPOSE_NETWORK_NAME** | Docker network name | `tsysdevstack-supportstack-demo-network` | +| **COMPOSE_NETWORK_NAME** | Docker network name | `kneldevstack-supportstack-demo-network` | ### 🎯 Deployment Scripts @@ -158,7 +158,7 @@ services: | Service | Health Check Path | Status | |---------|-------------------|--------| | **Pi-hole** (DNS Management) | `HTTP GET /` | ✅ Active | -| **Portainer** (Container Management) | `HTTP GET /` | ✅ Active | +| **Dockhand** (Container Management) | `HTTP GET /` | ✅ Active | | **InfluxDB** (Time Series Database) | `HTTP GET /ping` | ✅ Active | | **Grafana** (Visualization Platform) | `HTTP GET /api/health` | ✅ Active | | **Draw.io** (Diagramming Server) | `HTTP GET /` | ✅ Active | @@ -186,7 +186,7 @@ labels: | Service | Username | Password | 🔗 Access | |---------|----------|----------|-----------| | **Grafana** | `admin` | `demo_password` | [Login](http://localhost:4009) | -| **Portainer** | `admin` | `demo_password` | [Login](http://localhost:4007) | +| **Dockhand** | `admin` | `demo_password` | [Login](http://localhost:4007) | --- @@ -207,8 +207,9 @@ graph TD | Service | Dependencies | Status | |---------|--------------|--------| -| **Container Management** (Portainer) | Container Socket Proxy | 🔗 Required | +| **Container Management** (Dockhand) | Docker socket (direct mount) | 🔗 Required | | **Visualization Platform** (Grafana) | Time Series Database (InfluxDB) | 🔗 Required | +| **Video Archiving** (Tube Archivist) | Redis (ta-redis) + Elasticsearch (ta-elasticsearch) | 🔗 Required | | **All Other Services** | None | ✅ Standalone | --- @@ -265,10 +266,10 @@ ls -la /var/lib/docker/volumes/${COMPOSE_PROJECT_NAME}_*/ docker info # 🌐 Check network -docker network ls | grep tsysdevstack_supportstack +docker network ls | grep kneldevstack-supportstack-demo # 🔄 Recreate network -docker network create tsysdevstack_supportstack +docker network create --subnet 192.168.3.0/24 --gateway 192.168.3.1 kneldevstack-supportstack-demo-network ``` #### Port conflicts @@ -295,7 +296,7 @@ docker compose restart {service} |-------|---------|----------| | **DNS issues** | Pi-hole | Ensure Docker DNS settings allow custom DNS servers
Check that port 53 is available on the host | | **Database connection** | Grafana-InfluxDB | Verify both services are on the same network
Check database connectivity: `curl http://localhost:4008/ping` | -| **Container access** | Portainer | Ensure container socket is properly mounted
Check Container Socket Proxy service if used | +| **Container access** | Dockhand | Ensure container socket is properly mounted
Check Container Socket Proxy service if used | --- @@ -316,7 +317,7 @@ docker compose restart {service} ```bash # 📋 List volumes -docker volume ls | grep tsysdevstack +docker volume ls | grep kneldevstack # 🗑️ Clean up all data docker compose down -v diff --git a/demo/docs/api-docs/README.md b/demo/docs/api-docs/README.md index 1a79ba2..1d85464 100644 --- a/demo/docs/api-docs/README.md +++ b/demo/docs/api-docs/README.md @@ -7,7 +7,7 @@ This document provides API endpoint information for all services in the stack. ## Infrastructure Services APIs ### Docker Socket Proxy -- **Base URL**: `http://localhost:4005` +- **Base URL: http://docker-socket-proxy:2375 (internal only, not accessible from host)` - **API Version**: Docker Engine API - **Authentication**: None (restricted by proxy) - **Endpoints**: @@ -27,7 +27,7 @@ This document provides API endpoint information for all services in the stack. ### Dockhand - **Base URL**: `http://localhost:4007` -- **Authentication**: Direct Docker API access +- **Authentication**: Web UI with direct Docker socket access - **Features**: - Container lifecycle management - Compose stack orchestration @@ -156,10 +156,10 @@ This document provides API endpoint information for all services in the stack. ### Docker Socket Proxy Example ```bash # Get Docker version -curl http://localhost:4005/version +# curl http://localhost:4005/version (internal only) # List containers -curl http://localhost:4005/containers/json +# curl http://localhost:4005/containers/json (internal only) ``` ### InfluxDB Example @@ -255,7 +255,7 @@ All services provide health check endpoints: ### Testing APIs ```bash # Test all health endpoints -for port in 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do +for port in 4000 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do echo "Testing port $port..." curl -f -s "http://localhost:$port/health" || \ curl -f -s "http://localhost:$port/ping" || \ diff --git a/demo/docs/service-guides/README.md b/demo/docs/service-guides/README.md index 89fb0a0..b3ea8e6 100644 --- a/demo/docs/service-guides/README.md +++ b/demo/docs/service-guides/README.md @@ -33,7 +33,7 @@ All services are accessible through the Homepage dashboard at http://localhost:4 - **Homepage** (Port 4000): Central dashboard for service discovery - **Atomic Tracker** (Port 4012): Habit tracking and personal dashboard - **ArchiveBox** (Port 4013): Web archiving solution -- **Tube Archivist** (Port 4014): YouTube video archiving +- **Tube Archivist** (Port 4014): YouTube video archiving (requires internal ta-redis + ta-elasticsearch) - **Wakapi** (Port 4015): Open-source WakaTime alternative - **MailHog** (Port 4017): Web and API based SMTP testing - **Atuin** (Port 4018): Magical shell history synchronization diff --git a/demo/docs/troubleshooting/README.md b/demo/docs/troubleshooting/README.md index bf611b4..8f80029 100644 --- a/demo/docs/troubleshooting/README.md +++ b/demo/docs/troubleshooting/README.md @@ -55,10 +55,10 @@ docker stats **Solution**: ```bash # Check network exists -docker network ls | grep tsysdevstack +docker network ls | grep kneldevstack # Recreate network -docker network create tsysdevstack_supportstack-demo +docker network create --subnet 192.168.3.0/24 --gateway 192.168.3.1 kneldevstack-supportstack-demo-network # Restart stack docker compose down && docker compose up -d @@ -77,7 +77,7 @@ id cat demo.env | grep -E "(UID|GID)" # Fix volume permissions -sudo chown -R $(id -u):$(id -g) /var/lib/docker/volumes/tsysdevstack_* +sudo chown -R $(id -u):$(id -g) /var/lib/docker/volumes/kneldevstack-supportstack-demo_* ``` #### Issue: Docker group access @@ -98,13 +98,13 @@ newgrp docker **Solution**: ```bash # Check Pi-hole status -docker exec tsysdevstack-supportstack-demo-pihole pihole status +docker exec kneldevstack-supportstack-demo-pihole pihole status # Test DNS resolution nslookup google.com localhost # Restart DNS service -docker exec tsysdevstack-supportstack-demo-pihole pihole restartdns +docker exec kneldevstack-supportstack-demo-pihole pihole restartdns ``` #### Grafana Data Source Connection @@ -128,8 +128,8 @@ docker compose logs grafana # Check Dockhand logs docker compose logs dockhand -# Verify Docker socket access -docker exec tsysdevstack-supportstack-demo-dockhand docker version +# Verify Docker socket access (check socket is mounted) +docker inspect kneldevstack-supportstack-demo-dockhand --format '{{.Mounts}}' | grep docker.sock # Restart Dockhand docker compose restart dockhand @@ -198,13 +198,13 @@ docker stats # Network info docker network ls -docker network inspect tsysdevstack_supportstack-demo +docker network inspect kneldevstack-supportstack-demo ``` ### Health Checks ```bash # Test all endpoints -for port in 4000 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do +for port in 4000 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do curl -f -s --max-time 5 "http://localhost:$port" && echo "Port $port: OK" || echo "Port $port: FAIL" done ``` @@ -262,11 +262,10 @@ docker system prune -f - User must be in docker group ### Port Requirements -All ports 4000-4018 must be available: +The following host ports must be available (not a continuous range): - 4000: Homepage -- 4005: Docker Socket Proxy - 4006: Pi-hole -- 4007: Portainer +- 4007: Dockhand - 4008: InfluxDB - 4009: Grafana - 4010: Draw.io @@ -278,6 +277,8 @@ All ports 4000-4018 must be available: - 4017: MailHog - 4018: Atuin +Note: Docker Socket Proxy (4005), Redis, and Elasticsearch are internal-only and do not require host ports. + ## Contact and Support If issues persist after trying these solutions: