Welcome to the vext (Rhodium Standard Edition) documentation. This index helps you find the right guide for your needs.
Start here to understand what vext is and get it running:
-
README.md (Main Entry Point)
- Project overview and description
- Key features and technology stack
- Installation requirements and basic usage
- Architecture and design philosophy
- Read this first!
-
- Step-by-step installation instructions
- Multiple installation methods (source, package manager, Docker)
- Post-installation configuration
- Repository-specific setup for Git, Mercurial, and SVN
- Troubleshooting installation issues
-
- Starting and managing the daemon
- Sending notifications (basic and advanced)
- Repository hook configuration
- Configuration management
- Monitoring and debugging
- Advanced usage patterns
Learn more about what vext does and how it works:
-
- Problem statement and solution
- Core concepts and architecture
- Use cases and advantages
- Comparison with alternatives
- Deployment options
- Roadmap and future enhancements
-
- Comprehensive feature list
- Multi-version control system support
- Persistent connection management
- Flexible communication protocols
- Advanced features
- Feature comparison matrix
Deep dive into the technical implementation:
- TECHNOLOGY_STACK.md
- Language and runtime information
- Core and optional dependencies
- Architecture components
- Network protocols (IRC, JSON, HTTP)
- Data flow architecture
- Performance characteristics
- Security technologies
- Monitoring and observability
Purpose: Main project documentation, suitable for GitHub/GitLab README
Covers:
- 2-3 paragraph project description
- What irker does
- What vext improves
- Core functionality and use cases
- Key features (12 main features)
- Technology stack overview
- Installation requirements
- Basic usage examples
- Architecture overview
- Configuration options
- Use cases
- Troubleshooting guide
- License and status
Best For: Getting started, quick reference, GitHub visibility
Purpose: Executive-level project overview and strategy
Covers:
- Executive summary
- Problem statement (5 problems solved)
- Solution approach
- Core concept with diagram
- Primary and secondary use cases
- Technical architecture
- Advantages comparison table
- Technology stack summary
- Installation footprint
- Security considerations
- Performance characteristics
- Scalability approach
- Maintenance model
- Comparison with original irker
- Deployment options
- Roadmap (short, medium, long term)
Best For: Understanding project goals, stakeholder communication, planning
Purpose: Comprehensive feature documentation
Covers:
- 12 core features with detailed explanations
- Multi-VCS support (Git, Mercurial, SVN)
- Persistent connection management
- Flexible communication protocols (TCP, UDP, Email)
- JSON protocol details
- Multi-channel broadcasting
- Color formatting
- Configurable formats
- Rate limiting and flood prevention
- Comprehensive logging
- Flexible routing
- Performance optimization
- Security features
- 6 advanced features
- Feature comparison matrix
Best For: Feature comparison, capability assessment, planning integrations
Purpose: Technical implementation details
Covers:
- Python language and version support
- Core dependencies (standard library only)
- Optional dependencies
- Development tools
- Architecture components with code examples
- Concurrency model and threading
- Event loop pattern
- Network protocols (IRC RFC 1459, JSON, HTTP)
- Data flow pipeline
- State management
- Performance profiles
- Deployment architecture
- System requirements
- Operating system support
- Systemd integration
- Configuration as code
- Security technologies
- Monitoring and observability
- Version management
- Integration points
Best For: Architecture understanding, integration planning, deployment design
Purpose: Step-by-step installation and configuration
Covers:
- Prerequisites and requirements
- 4 installation methods:
- From source with virtual environment
- Package manager (Ubuntu, CentOS, macOS)
- Docker container deployment
- System-wide manual installation
- Post-installation configuration:
- Config file creation
- Log directory setup
- Environment variables
- Repository-specific setup:
- Git post-receive hook
- Mercurial hook integration
- Subversion hook configuration
- Testing procedures
- Troubleshooting common issues
- Uninstallation instructions
Best For: Getting vext running, setting up hooks, troubleshooting setup issues
Purpose: Operational guide for running vext
Covers:
- Quick start (3 steps)
- Daemon management:
- Command-line options
- Systemd service management
- Manual service management
- Sending notifications:
- Basic notifications
- Multi-channel routing
- Color formatting
- Custom nicknames
- Python script examples
- TCP vs UDP
- Bash script helpers
- Repository hook configuration:
- Git (basic and advanced)
- Mercurial
- Subversion
- Configuration management
- Monitoring and troubleshooting:
- Status checks
- IRC connectivity testing
- Hook debugging
- Common issues
- Advanced usage patterns
- Performance tuning
Best For: Daily operations, troubleshooting, integration examples
Purpose: Navigation and organization guide
- Total Documentation Files: 6 markdown files + this index
- Total Lines: ~2,935 lines of documentation
- Total Coverage:
- Project overview and strategy
- Complete feature list
- Technical architecture
- Installation procedures
- Usage and operations
- Troubleshooting and support
- Getting Started: README.md → INSTALLATION_GUIDE.md
- Docker Setup: INSTALLATION_GUIDE.md
- Git Hook Setup: INSTALLATION_GUIDE.md
- Post-Installation: INSTALLATION_GUIDE.md
- Starting Daemon: USAGE_GUIDE.md
- Sending Notifications: USAGE_GUIDE.md
- Debugging Issues: USAGE_GUIDE.md
- Performance Tuning: USAGE_GUIDE.md
- Feature List: FEATURES.md
- VCS Support: FEATURES.md
- Protocols: FEATURES.md
- Advanced Features: FEATURES.md
- Architecture: TECHNOLOGY_STACK.md
- Performance: TECHNOLOGY_STACK.md
- Security: TECHNOLOGY_STACK.md
- System Requirements: TECHNOLOGY_STACK.md
- Overview: PROJECT_OVERVIEW.md
- Use Cases: PROJECT_OVERVIEW.md
- Roadmap: PROJECT_OVERVIEW.md
README.md (Entry Point)
├─ Quick overview
├─ Links to: INSTALLATION_GUIDE.md, USAGE_GUIDE.md
└─ References: FEATURES.md, TECHNOLOGY_STACK.md
PROJECT_OVERVIEW.md (Strategic View)
├─ What and why?
├─ References: README.md
└─ Links to: INSTALLATION_GUIDE.md, FEATURES.md
FEATURES.md (Capabilities)
├─ What can it do?
├─ References: README.md
└─ Links to: USAGE_GUIDE.md, TECHNOLOGY_STACK.md
TECHNOLOGY_STACK.md (Implementation)
├─ How is it built?
├─ References: README.md, FEATURES.md
└─ Links to: INSTALLATION_GUIDE.md
INSTALLATION_GUIDE.md (Getting Started)
├─ How to install?
├─ References: README.md
└─ Links to: USAGE_GUIDE.md, POST_CONFIGURATION
USAGE_GUIDE.md (Operations)
├─ How to use?
├─ References: INSTALLATION_GUIDE.md
└─ Links to: TROUBLESHOOTING
- Start: PROJECT_OVERVIEW.md
- Then: FEATURES.md
- Reference: README.md
- Start: README.md
- Then: INSTALLATION_GUIDE.md
- Reference: USAGE_GUIDE.md, TECHNOLOGY_STACK.md
- Start: INSTALLATION_GUIDE.md
- Then: USAGE_GUIDE.md
- Reference: PROJECT_OVERVIEW.md
- Start: TECHNOLOGY_STACK.md
- Then: FEATURES.md
- Reference: USAGE_GUIDE.md
"What is vext?" → Read README.md (Project Overview section)
"How do I install it?" → Follow INSTALLATION_GUIDE.md
"How do I use it?" → See USAGE_GUIDE.md
"Does it support my VCS?" → Check FEATURES.md
"What are the requirements?" → Review README.md
"How does it work?" → Study TECHNOLOGY_STACK.md
"Can I customize it?" → See FEATURES.md and USAGE_GUIDE.md
"What's the roadmap?" → Check PROJECT_OVERVIEW.md
All documentation follows these standards:
- Markdown format for GitHub/GitLab compatibility
- Clear structure with headers, sections, and subsections
- Practical examples for most features
- Code blocks with language specification
- Tables for comparisons and matrices
- Links between related documents
- TOC-friendly with descriptive headers
- Accessible to both technical and non-technical readers
When adding new documentation:
- Follow the structure and style of existing documents
- Add new files and update this index
- Link to related documents using markdown links
- Include practical examples where applicable
- Update the file statistics above
- Ensure markdown validates correctly
- Documentation Version: 1.0
- Last Updated: 2025-11-22
- vext Version: Rhodium Standard Edition
- Related Project: irker (by Eric S. Raymond)
All documentation is provided under the same license as vext: Eclipse Public License 2.0
Start with README.md if you're new to vext!