docs(demo): synchronize all documentation with 16-service stack
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 <crush@charm.land>
This commit is contained in:
reachableceo
38
AGENTS.md
38
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 <path-to-dockerfile>
|
||||
## 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 <path-to-dockerfile>
|
||||
- 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 <path-to-dockerfile>
|
||||
## Naming Conventions & Style Patterns
|
||||
|
||||
### Service Naming
|
||||
- **Container Names**: `tsysdevstack-supportstack-demo-<service-name>`
|
||||
- **Volume Names**: `tsysdevstack-supportstack-demo-<service>_data`
|
||||
- **Network Name**: `tsysdevstack-supportstack-demo-network`
|
||||
- **Project Name**: `tsysdevstack-supportstack-demo`
|
||||
- **Container Names**: `kneldevstack-supportstack-demo-<service-name>`
|
||||
- **Volume Names**: `kneldevstack-supportstack-demo_<service>_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-<service>_data`
|
||||
- **Dynamic Naming**: Volume names follow pattern: `kneldevstack-supportstack-demo_<service>_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 <image>` manually
|
||||
4. **Health Check Failures**: Check service logs with `docker compose logs <service>`
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user