{"id":28388305,"url":"https://github.com/bytebrushstudios/void","last_synced_at":"2026-04-25T23:33:41.480Z","repository":{"id":296202598,"uuid":"992592688","full_name":"ByteBrushStudios/void","owner":"ByteBrushStudios","description":"A modern, high-performance reverse proxy and maintenance system.","archived":false,"fork":false,"pushed_at":"2025-05-29T13:03:46.000Z","size":3014,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-06T21:15:47.514Z","etag":null,"topics":["docker","dokploy","maintenance","nginx","nginx-proxy","reverese-proxy","reverse-proxy-server","traefik"],"latest_commit_sha":null,"homepage":"https://void.bytebrush.dev","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ByteBrushStudios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-05-29T12:04:37.000Z","updated_at":"2025-05-29T13:03:50.000Z","dependencies_parsed_at":"2025-05-29T13:42:42.807Z","dependency_job_id":"36b0048a-552c-4b35-b0d3-196e30b16709","html_url":"https://github.com/ByteBrushStudios/void","commit_stats":null,"previous_names":["bytebrushstudios/void"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ByteBrushStudios/void","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteBrushStudios%2Fvoid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteBrushStudios%2Fvoid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteBrushStudios%2Fvoid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteBrushStudios%2Fvoid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ByteBrushStudios","download_url":"https://codeload.github.com/ByteBrushStudios/void/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteBrushStudios%2Fvoid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280974,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["docker","dokploy","maintenance","nginx","nginx-proxy","reverese-proxy","reverse-proxy-server","traefik"],"created_at":"2025-05-30T21:11:54.133Z","updated_at":"2026-04-25T23:33:41.475Z","avatar_url":"https://github.com/ByteBrushStudios.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Void ⚡\n\n`Void` is a modern, high-performance reverse proxy and maintenance system developed by `ByteBrush Studios`. It provides intelligent traffic routing with beautiful, techy maintenance pages when services are unavailable. Built with Go for exceptional performance and featuring a stunning glassmorphic UI with animated backgrounds.\n\n## ✨ Features\n\n- **🔄 Intelligent Reverse Proxy**: Automatically routes traffic to healthy backends and shows maintenance pages when services are down\n- **🎨 Modern UI**: Beautiful glassmorphic design with animated backgrounds and smooth transitions\n- **⚡ High Performance**: Built with Go's concurrency model for lightning-fast response times\n- **📱 Responsive Design**: Works flawlessly on desktop, tablet, and mobile devices\n- **🛠️ Debug Information**: Built-in debugging tools with client and server information\n- **🌐 Multi-Service Support**: Manage multiple services with individual configurations\n- **📊 Smart API Handling**: JSON responses for API endpoints during maintenance\n- **🔧 Easy Configuration**: Simple YAML-based service configuration\n- **🐳 Container Ready**: Docker and Kubernetes compatible\n- **🚀 Multiple Deployment Options**: Works with Nginx, Traefik, Dokploy, and more\n\n---\n\n## 🖼️ Preview\n\nExperience the modern, techy interface of Void:\n\n![Debug Panel Closed](assets/previews/debug_closed.png)\n*Clean, modern maintenance page with glassmorphic design*\n\n![Debug Panel Open](assets/previews/debug_open.png)  \n*Comprehensive debug information with syntax highlighting*\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Go 1.18 or higher (for building from source)\n- OR Docker (for containerized deployment)\n\n### Option 1: Binary Installation\n\n1. **Download and Build**\n   ```bash\n   git clone https://github.com/ByteBrushStudios/void.git\n   cd void\n   make build\n   ```\n\n2. **Configure Services**\n   ```bash\n   # Copy example service configuration\n   mkdir -p services\n   cp examples/services/example.yaml services/myapp.yaml\n   # Edit the configuration file\n   ```\n\n3. **Run Void**\n   ```bash\n   ./void\n   ```\n\n### Option 2: Docker Deployment\n\n1. **Using Docker Compose**\n   ```bash\n   git clone https://github.com/ByteBrushStudios/void.git\n   cd void\n   cp examples/services.yaml.example services.yaml\n   docker-compose -f examples/docker-compose.yml up -d\n   ```\n\nVoid will start on port `1292` by default and begin reverse proxying to your configured services.\n\n---\n\n## ⚙️ Configuration\n\n### Service Configuration\n\nVoid uses YAML configuration files in the `services` directory to define your services:\n\n```yaml\n# services/myapp.yaml\nservices:\n  - name: \"My Web Application [Production]\"\n    host: \"http://127.0.0.1:3000\"    # Backend server URL\n    domain: \"myapp.com\"              # Domain to match requests\n    support: \"https://discord.gg/support\"\n    status: \"https://status.myapp.com\"\n```\n\nYou can create multiple YAML files to organize your services by project or environment.\n\n#### How It Works\n\n1. **Healthy Service**: Void reverse proxies requests to the backend defined in `host`\n2. **Unhealthy Service**: Void displays the beautiful maintenance page\n3. **API Endpoints**: Services listed in `apiUrls` receive JSON responses during maintenance\n\n#### Configuration Fields\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| `name` | Display name for the service | `\"My App [Production]\"` |\n| `host` | Backend server URL for reverse proxy | `\"http://127.0.0.1:3000\"` |\n| `domain` | Domain to match requests against | `\"myapp.com\"` |\n| `support` | Support/contact URL | `\"https://discord.gg/support\"` |\n| `status` | Status page URL | `\"https://status.myapp.com\"` |\n\n---\n\n## 🌐 Deployment Options\n\n### Nginx Integration\n\nPerfect for traditional server setups. Void acts as a fallback when your main services are down.\n\n```bash\n# Copy the example configuration\ncp examples/nginx.conf /etc/nginx/sites-available/your-site\n# Edit and enable the configuration\nsudo nginx -t \u0026\u0026 sudo systemctl reload nginx\n```\n\nSee `examples/nginx.conf` for a complete production-ready configuration.\n\n### Traefik Integration\n\nIdeal for containerized environments with automatic service discovery.\n\n```bash\n# Copy Traefik configuration\ncp examples/traefik.yml /etc/traefik/\n# Void integrates seamlessly with Traefik's circuit breaker middleware\n```\n\n### Dokploy Deployment\n\nModern deployment platform with built-in container orchestration.\n\n```bash\n# Import the Dokploy configuration\ndokploy import examples/dokploy.json\n# Deploy with zero-downtime rolling updates\n```\n\n### Systemd Service\n\nFor production server deployments:\n\n```bash\n# Copy service file\nsudo cp examples/void.service /etc/systemd/system/\n# Enable and start\nsudo systemctl daemon-reload\nsudo systemctl enable void.service\nsudo systemctl start void.service\n```\n\n---\n\n## 🔧 Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `VOID_PORT` | Server port | `1292` |\n| `VOID_LOG_LEVEL` | Log level (debug, info, warn, error) | `info` |\n\n---\n\n## 📊 Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Load Balancer │────│      Void       │────│  Backend Apps   │\n│  (Nginx/Traefik)│    │ Reverse Proxy   │    │ (Your Services) │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n                              │\n                              ▼\n                      ┌─────────────────┐\n                      │ Maintenance UI  │\n                      │ (When backend   │\n                      │  is unhealthy)  │\n                      └─────────────────┘\n```\n\n### Request Flow\n\n1. **Incoming Request** → Load balancer routes to Void\n2. **Domain Matching** → Void matches request domain to configured service\n3. **Health Check** → Void attempts to proxy to backend service\n4. **Success** → Request proxied to healthy backend\n5. **Failure** → Beautiful maintenance page served (HTML) or JSON response (APIs)\n\n---\n\n## 🔍 Features Deep Dive\n\n### Intelligent Reverse Proxy\n- **Automatic Failover**: Seamlessly switches between backend and maintenance mode\n- **Domain-Based Routing**: Route different domains to different backend services\n- **Health Detection**: Automatically detects when services are available again\n- **Header Preservation**: Maintains original request headers for proper backend handling\n\n### Smart API Handling\n```yaml\napiUrls:\n  - \"api.example.com\"\n  - \"webhooks.example.com\"\n```\nAPI endpoints receive structured JSON responses instead of HTML:\n```json\n{\n  \"message\": \"This service is down for maintenance...\",\n  \"service\": {\n    \"name\": \"API Server [Production]\",\n    \"domain\": \"api.example.com\",\n    \"support\": \"https://support.example.com\",\n    \"status\": \"https://status.example.com\"\n  },\n  \"info\": {\n    \"version\": \"2.0.0-alpha.1\",\n    \"commit\": \"abc123\"\n  }\n}\n```\n\n### Debug Information\nThe debug panel provides comprehensive diagnostics:\n- **Server Info**: Void version, commit hash, routing details\n- **Client Info**: IP address, geolocation, browser details with privacy controls\n- **Request Details**: Path, hostname, and routing information\n\n### Modern UI Features\n- **Animated Background**: Subtle particle animations and grid patterns\n- **Glassmorphic Design**: Modern blur effects and transparency\n- **Smooth Transitions**: Buttery smooth animations and micro-interactions\n- **Responsive Layout**: Perfect on all screen sizes and devices\n- **Dark Theme**: Modern color palette optimized for readability\n\n---\n\n## 🛠️ Development\n\n### Project Structure\n\n```\nvoid/\n├── main.go                    # Main application entry point\n├── services.yaml             # Service configuration\n├── app.html                  # Modern maintenance page template\n├── assets/                   # Static assets (images, icons)\n│   └── previews/            # UI preview images\n├── state/                   # Application state management\n├── types/                   # Type definitions and structs\n├── examples/                # Configuration examples\n│   ├── nginx.conf          # Nginx integration example\n│   ├── traefik.yml         # Traefik configuration\n│   ├── dokploy.json        # Dokploy deployment config\n│   ├── void.service        # Systemd service template\n│   ├── docker-compose.yml  # Docker Compose setup\n│   └── services.yaml.example # Service configuration example\n├── temp/                   # Temporary files and drafts\n└── README.md               # This documentation\n```\n\n### Building from Source\n\n```bash\n# Install dependencies and build\nmake build\n\n# Run in development mode with hot reload\nmake dev\n\n# Run tests\nmake test\n\n# Build for production with optimizations\nmake release\n```\n\n### API Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `/*` | Main router - handles all requests with domain matching |\n| `/__voidStatic/*` | Static assets (CSS, JS, images) |\n\n---\n\n## 🔧 Advanced Configuration\n\n### Load Balancing Integration\n\nVoid works excellently behind load balancers:\n\n**HAProxy Example:**\n```haproxy\nbackend void_maintenance\n    server void1 127.0.0.1:1292 check\n\nbackend app_servers\n    option httpchk GET /health\n    server app1 127.0.0.1:3000 check fall 3 rise 2\n    server app2 127.0.0.1:3001 check fall 3 rise 2\n\nfrontend web_frontend\n    default_backend app_servers\n    # Fallback to maintenance on 5xx errors\n    errorfile 503 /dev/null\n    errorloc 503 http://void-maintenance:1292\n```\n\n### Container Orchestration\n\n**Kubernetes Example:**\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: void-maintenance\nspec:\n  replicas: 2\n  selector:\n    matchLabels:\n      app: void\n  template:\n    metadata:\n      labels:\n        app: void\n    spec:\n      containers:\n      - name: void\n        image: void:latest\n        ports:\n        - containerPort: 1292\n        env:\n        - name: VOID_PORT\n          value: \"1292\"\n        - name: VOID_LOG_LEVEL\n          value: \"info\"\n```\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork \u0026 Clone**\n   ```bash\n   git clone https://github.com/your-username/void.git\n   cd void\n   ```\n\n2. **Create Feature Branch**\n   ```bash\n   git checkout -b feature/amazing-feature\n   ```\n\n3. **Make Changes \u0026 Test**\n   ```bash\n   make test\n   make dev  # Test your changes\n   ```\n\n4. **Commit \u0026 Push**\n   ```bash\n   git commit -m \"feat: add amazing feature\"\n   git push origin feature/amazing-feature\n   ```\n\n5. **Open Pull Request**\n\n### Development Guidelines\n- Follow Go best practices and `gofmt` formatting\n- Add tests for new features\n- Update documentation for any API changes\n- Ensure backwards compatibility\n- Test with multiple deployment scenarios\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n### Open Source Credits\n- [Go](https://golang.org/) - The Go Programming Language\n- [Chi Router](https://github.com/go-chi/chi) - Lightweight HTTP router\n- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework\n- [Iconify](https://iconify.design/) - Unified icon framework\n- [ipapi.co](https://ipapi.co/) - IP geolocation API\n\n---\n\n## 🆘 Support \u0026 Community\n\n- **📚 Documentation**: This README and inline code comments\n- **🐛 Issues**: [GitHub Issues](https://github.com/ByteBrushStudios/void/issues)\n- **💬 Discussions**: [GitHub Discussions](https://github.com/ByteBrushStudios/void/discussions)\n- **💬 Discord**: Join our [community](https://discord.gg/Vv2bdC44Ge)\n- **📧 Email**: [hey@bytebrush.dev](mailto:hey@bytebrush.dev)\n\n---\n\n## 🏢 About ByteBrush Studios!\n\nVoid is developed and maintained by [ByteBrush Studios](https://bytebrush.dev), creators of high-quality open-source software for developers and businesses.\n\n**Other Projects:**\n- [Infinity Bot List](https://infinitybots.gg/) - The next generation Discord bot list\n- [Eureka](https://github.com/infinitybotlist/eureka) - Powerful logging and utilities library\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⭐ Star this repo](https://github.com/ByteBrushStudios/void) • [🐛 Report Bug](https://github.com/ByteBrushStudios/void/issues) • [💡 Request Feature](https://github.com/ByteBrushStudios/void/discussions)**\n\nMade with ❤️ by ByteBrush Studios\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebrushstudios%2Fvoid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytebrushstudios%2Fvoid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebrushstudios%2Fvoid/lists"}