{"id":28937165,"url":"https://github.com/roadrunner-php/velox-app","last_synced_at":"2026-06-14T01:32:46.985Z","repository":{"id":300553702,"uuid":"1006377759","full_name":"roadrunner-php/velox-app","owner":"roadrunner-php","description":"RoadRunner binary Builder","archived":false,"fork":false,"pushed_at":"2025-11-08T07:46:14.000Z","size":576,"stargazers_count":5,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-08T09:15:28.637Z","etag":null,"topics":["go","php","roadrunner","velox"],"latest_commit_sha":null,"homepage":"https://build.roadrunner.dev/","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roadrunner-php.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-22T06:03:31.000Z","updated_at":"2025-11-08T07:44:14.000Z","dependencies_parsed_at":"2025-08-10T22:32:53.135Z","dependency_job_id":"2f4a9733-7aac-4c72-9a44-293083714ed2","html_url":"https://github.com/roadrunner-php/velox-app","commit_stats":null,"previous_names":["roadrunner-php/velox-app"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/roadrunner-php/velox-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-php%2Fvelox-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-php%2Fvelox-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-php%2Fvelox-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-php%2Fvelox-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roadrunner-php","download_url":"https://codeload.github.com/roadrunner-php/velox-app/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roadrunner-php%2Fvelox-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34306772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","php","roadrunner","velox"],"created_at":"2025-06-22T21:03:35.350Z","updated_at":"2026-06-14T01:32:46.943Z","avatar_url":"https://github.com/roadrunner-php.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Velox Configuration Builder\n\n## 🧭 Purpose of the Component\n\nVelox Configuration Builder is a comprehensive web application that simplifies the creation of custom RoadRunner server\nconfigurations. It allows developers to visually select plugins, resolve dependencies automatically, and generate\nproduction-ready configurations with just a few clicks, eliminating the complexity of manual TOML configuration and\nbinary building.\n\n## 📝 Detailed Description for Business Analyst and Marketing\n\nThe Velox Configuration Builder solves a critical problem in the PHP application server ecosystem. RoadRunner is a\npowerful application server, but configuring it with the right plugins and dependencies can be extremely complex and\ntime-consuming for development teams.\n\n**Business Problem Solved:**\n\n- **Complexity Reduction**: Manual RoadRunner configuration requires deep technical knowledge of plugin dependencies and\n  version compatibility\n- **Time Savings**: What used to take hours of research and testing now takes minutes with visual selection\n- **Error Prevention**: Automatic dependency resolution prevents configuration conflicts that could break production\n  systems\n- **Standardization**: Teams can use predefined presets ensuring consistent configurations across projects\n\n**Business Value:**\n\n- **Faster Time-to-Market**: Developers can focus on business logic instead of infrastructure configuration\n- **Reduced Support Costs**: Fewer configuration-related issues mean less debugging and support overhead\n- **Improved Developer Experience**: Visual interface makes RoadRunner accessible to developers of all skill levels\n- **Enterprise Readiness**: Built-in validation and best practices ensure production-ready configurations\n\n**System Integration:**\nThis component serves as the central orchestrator for RoadRunner server customization, integrating with GitHub/GitLab\nrepositories for plugin management, Docker for containerization, and providing both web UI and CLI interfaces for\ndifferent user preferences.\n\n## 🔄 Mermaid Sequence Diagram for Business Analyst and Marketing\n\n### Plugin Selection and Configuration Generation Flow\n\n```mermaid\nsequenceDiagram\n    participant User as Developer\n    participant UI as Web Interface\n    participant CB as Configuration Builder\n    participant PP as Plugin Provider\n    participant DR as Dependency Resolver\n    participant CG as Config Generator\n    participant VB as Binary Builder\n    User -\u003e\u003e UI: Select plugins or presets\n    UI -\u003e\u003e CB: Request configuration build\n    CB -\u003e\u003e PP: Get available plugins\n    PP --\u003e\u003e CB: Return plugin catalog\n    CB -\u003e\u003e DR: Resolve dependencies\n    DR --\u003e\u003e CB: Return dependency tree\n    CB -\u003e\u003e CG: Generate TOML config\n    CG --\u003e\u003e CB: Return configuration\n    CB -\u003e\u003e VB: Build RoadRunner binary\n    VB --\u003e\u003e CB: Return build result\n    CB --\u003e\u003e UI: Configuration + Binary ready\n    UI --\u003e\u003e User: Download files + Docker setup\n```\n\n### Preset-Based Configuration Flow\n\n```mermaid\nsequenceDiagram\n    participant User as Developer\n    participant PS as Preset Service\n    participant PM as Preset Merger\n    participant CB as Configuration Builder\n    participant VB as Binary Builder\n    User -\u003e\u003e PS: Select presets (web-server, monitoring)\n    PS -\u003e\u003e PM: Merge selected presets\n    PM --\u003e\u003e PS: Combined plugin list\n    PS -\u003e\u003e CB: Build configuration from plugins\n    CB -\u003e\u003e VB: Generate binary + Docker files\n    VB --\u003e\u003e CB: Complete package\n    CB --\u003e\u003e User: Ready-to-deploy solution\n```\n\n### Version Management and Updates Flow\n\n```mermaid\nsequenceDiagram\n    participant Admin as System Admin\n    participant VM as Version Manager\n    participant GH as GitHub API\n    participant EF as Environment File\n    participant CB as Configuration Builder\n    Admin -\u003e\u003e VM: Check for plugin updates\n    VM -\u003e\u003e GH: Query latest versions\n    GH --\u003e\u003e VM: Return version info\n    VM -\u003e\u003e EF: Update environment variables\n    VM --\u003e\u003e Admin: Update summary\n    Admin -\u003e\u003e CB: Rebuild with new versions\n    CB --\u003e\u003e Admin: Updated configuration\n```\n\n## 🧍 List of Actors\n\n- **Developer**: Primary user who selects plugins and generates RoadRunner configurations\n- **DevOps Engineer**: Uses generated Docker files and configurations for deployment\n- **System Administrator**: Manages plugin versions and updates across the organization\n- **Business Analyst**: Reviews presets and configuration templates for different use cases\n- **GitHub/GitLab APIs**: External services providing plugin repositories and version information\n- **Docker Registry**: Target for generated container images\n- **CI/CD Pipeline**: Automated systems that consume generated configurations\n- **RoadRunner Server**: The target application server that runs the generated configuration\n\n## 📐 List of Business Rules\n\n### Plugin Management Rules\n\n- **Official Plugin Priority**: Official RoadRunner plugins take precedence over community plugins in conflict\n  resolution\n- **Version Compatibility**: Only plugins with compatible major versions can be selected together\n- **Dependency Enforcement**: Required dependencies must be automatically included when a plugin is selected\n- **GitHub Rate Limiting**: Anonymous GitHub access is limited to 50 requests/hour; authenticated access is required for\n  production use\n\n### Configuration Validation Rules\n\n- **Minimum Requirements**: Every configuration must include the 'server' plugin as it's essential for RoadRunner\n  operation\n- **Token Validation**: GitHub/GitLab tokens are recommended when using respective platform plugins to avoid rate\n  limiting\n- **Master Branch Warning**: Using 'master' branch in production configurations triggers validation warnings\n- **Plugin Count Limits**: Configurations with excessive plugins (\u003e20) receive performance warnings\n\n### Preset Management Rules\n\n- **Preset Priority**: Higher priority presets override lower priority ones during merging\n- **Conflict Detection**: Presets containing conflicting functionality groups trigger warnings\n- **Completeness Validation**: All plugins referenced in presets must exist in the plugin catalog\n- **Tag-Based Filtering**: Presets can be filtered by environment tags (production, development, testing)\n\n### Binary Building Rules\n\n- **Build Timeout**: Binary builds automatically timeout after 300 seconds (configurable)\n- **Clean Build Environment**: Each build uses an isolated temporary directory\n- **Size Optimization**: Generated binaries exclude debug symbols unless explicitly enabled\n- **Velox Dependency**: Binary building requires the 'vx' command-line tool to be available\n\n| Rule Category         | Validation Type | Action              | Business Impact                                |\n|-----------------------|-----------------|---------------------|------------------------------------------------|\n| Plugin Dependencies   | Error           | Block configuration | Prevents broken deployments                    |\n| Version Compatibility | Warning         | Allow with notice   | Maintains flexibility while highlighting risks |\n| Token Requirements    | Warning         | Allow with notice   | Prevents rate limiting issues                  |\n| Build Requirements    | Error           | Block build         | Ensures build environment is ready             |\n\n## 📚 Domain Ubiquitous Terminology\n\n- **Velox**: The RoadRunner binary builder tool that compiles custom server configurations\n- **Plugin**: Modular component that adds specific functionality to RoadRunner (HTTP, Jobs, KV storage)\n- **Preset**: Pre-defined combination of plugins optimized for specific use cases (web-server, queue-server)\n- **Dependency Resolution**: Automatic process of including required plugins when others are selected\n- **TOML Configuration**: Human-readable configuration file format used by RoadRunner\n- **Binary Building**: Process of compiling a custom RoadRunner executable with selected plugins\n- **Repository Type**: Platform hosting the plugin (GitHub or GitLab)\n- **Plugin Source**: Classification of plugin origin (Official from RoadRunner team vs Community)\n- **Environment Variables**: Configuration values stored in .env files for tokens and plugin versions\n- **Docker Artifact**: Generated Dockerfile and related files for containerized deployment\n- **Plugin Category**: Functional grouping (Core, HTTP, Jobs, KV, Metrics, etc.)\n- **Version Ref**: Git reference (tag, branch, or commit) specifying which plugin version to use\n- **Build Hash**: Unique identifier for a specific configuration build for caching purposes\n\n## 🧪 Simple Use Cases\n\n### Use Case 1: New Developer Creates Web Server Configuration\n\n**Actor**: Junior PHP Developer\n**Goal**: Create a simple HTTP server configuration for a new project\n\n**Steps**:\n\n1. Developer opens Velox Configuration Builder web interface\n2. Selects \"web-server\" preset from the available options\n3. System automatically includes: server, logger, http, headers, gzip, static, fileserver, status plugins\n4. Developer reviews the generated configuration in the preview panel\n5. Clicks \"Generate\" to create TOML configuration and Dockerfile\n6. Downloads the package and deploys using Docker\n\n**Outcome**: Working RoadRunner server ready for PHP web application in under 5 minutes\n\n### Use Case 2: DevOps Engineer Builds Custom Microservices Setup\n\n**Actor**: Senior DevOps Engineer\n**Goal**: Create optimized configuration for microservices architecture\n\n**Steps**:\n\n1. Engineer selects individual plugins: server, logger, http, grpc, rpc, metrics, prometheus, otel\n2. System validates dependencies and suggests additional required plugins\n3. Engineer reviews dependency tree and approves automatic inclusions\n4. Configures GitHub token for authenticated plugin downloads\n5. Generates both TOML configuration and builds binary directly\n6. System provides complete package with binary, Dockerfile, and monitoring setup\n\n**Outcome**: Production-ready microservices server with full observability stack\n\n### Use Case 3: System Administrator Updates Plugin Versions\n\n**Actor**: System Administrator\n**Goal**: Keep all plugin versions current and secure across the organization\n\n**Steps**:\n\n1. Administrator runs version check command via CLI\n2. System queries GitHub APIs for latest stable plugin versions\n3. Generates report showing outdated plugins and recommended updates\n4. Administrator approves updates for compatible versions\n5. System updates environment configuration files\n6. New configurations are rebuilt automatically with updated plugin versions\n\n**Outcome**: All RoadRunner deployments use latest secure plugin versions with minimal manual intervention","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froadrunner-php%2Fvelox-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froadrunner-php%2Fvelox-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froadrunner-php%2Fvelox-app/lists"}