{"id":36877613,"url":"https://github.com/aichy126/onedock","last_synced_at":"2026-01-14T19:43:32.651Z","repository":{"id":310359775,"uuid":"1039599084","full_name":"aichy126/onedock","owner":"aichy126","description":"🐳 Smart Docker container orchestration with intelligent load balancing and automatic port management. Built with Go + Gin framework.","archived":false,"fork":false,"pushed_at":"2025-08-19T12:23:41.000Z","size":135,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T19:59:51.274Z","etag":null,"topics":["container-orchestration","containerization","devops","docker","docker-management","golang","load-balancing","port-management","proxy-server","scaling"],"latest_commit_sha":null,"homepage":"","language":"Go","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/aichy126.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-08-17T15:31:25.000Z","updated_at":"2025-10-17T16:20:51.000Z","dependencies_parsed_at":"2025-08-17T16:30:06.395Z","dependency_job_id":"c10fd80d-be5e-4e87-9f9b-ccf8e6645c09","html_url":"https://github.com/aichy126/onedock","commit_stats":null,"previous_names":["aichy126/onedock"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/aichy126/onedock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aichy126%2Fonedock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aichy126%2Fonedock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aichy126%2Fonedock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aichy126%2Fonedock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aichy126","download_url":"https://codeload.github.com/aichy126/onedock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aichy126%2Fonedock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28432681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T18:57:19.464Z","status":"ssl_error","status_checked_at":"2026-01-14T18:52:48.501Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["container-orchestration","containerization","devops","docker","docker-management","golang","load-balancing","port-management","proxy-server","scaling"],"created_at":"2026-01-12T15:14:29.996Z","updated_at":"2026-01-14T19:43:32.636Z","avatar_url":"https://github.com/aichy126.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OneDock\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Go Version](https://img.shields.io/badge/go-1.24+-blue.svg)](https://golang.org)\n[![Build Status](https://github.com/aichy126/onedock/workflows/CI/badge.svg)](https://github.com/aichy126/onedock/actions)\n[![Go Report Card](https://goreportcard.com/badge/github.com/aichy126/onedock)](https://goreportcard.com/report/github.com/aichy126/onedock)\n\n[中文文档](README_zh.md) | English\n\nA powerful Docker container orchestration service built with Go and Gin framework, providing RESTful APIs for deploying, managing, and scaling containerized services with intelligent port proxying and load balancing.\n\n## 🎯 Use Cases \u0026 Applications\n\n### 🎯 Target Scenarios\n\nOneDock is designed as a **lightweight container orchestration solution** for **small to medium teams** and **single-machine container deployments**, perfectly bridging the gap between Docker and Kubernetes:\n\n#### 🔥 Core Application Scenarios\n\n**1. Small-Scale Container Orchestration**\n- Container deployment needs for single machine or few servers\n- Don't need K8s complexity, but require stronger API control than Docker Compose\n- Prefer RESTful API management over configuration files\n\n**2. CI/CD Automation \u0026 Deployment**\n- Seamless integration with existing CI/CD pipelines through API\n- Support for blue-green deployment and rolling update strategies\n- Real-time deployment monitoring with quick rollback capabilities\n\n**3. Microservices Rapid Prototyping**\n- Quick deployment and testing of microservice architectures\n- Zero-configuration load balancing with automatic service discovery\n- Dynamic scaling to easily validate performance characteristics\n\n**4. Development/Testing Environment Management**\n- Quickly set up consistent testing environments for development teams\n- Fast service version switching through API\n- Transparent resource usage for cost control\n\n#### 🚀 When to Choose OneDock?\n\n✅ **Perfect for OneDock:**\n- Need API-driven container orchestration (not configuration files)\n- Single machine or 2-5 server deployment scale\n- Want zero-configuration load balancing and service discovery\n- Need integration with existing CI/CD systems\n- Want quick setup with 10-minute deployment\n\n❌ **Not suitable for:**\n- Large-scale cluster management (recommend K8s)\n- Complex cross-node network policies\n- Advanced scheduling features (affinity, anti-affinity, etc.)\n- Multi-tenancy and complex permission management\n\n### 💡 Core Advantages\n\n**Simple but Not Simplistic:**\n- Single binary file, 5-minute installation\n- RESTful API design, integrates with any tech stack\n- Intelligent load balancing, auto-adapts to single/multi-replica scenarios\n- Built-in health checks and monitoring, minimal operational burden\n\n**Powerful yet Flexible:**\n- Rolling updates ensure service continuity\n- Dynamic scaling without service restart\n- Complete Swagger documentation with online testing\n- Multiple load balancing strategies for different performance needs\n\n## ✨ Features\n\n- **🚀 Container Lifecycle Management**: Deploy, update, delete, and scale containerized services\n- **🔄 Smart Port Management**: Automatic port allocation starting from configured base port\n- **⚖️ Intelligent Load Balancing**: Automatically switch between single-replica proxy and load balancer based on replica count\n- **📦 Cache Optimization**: Port mapping cache with TTL and manual cleanup support\n- **🔧 Service Recovery**: Auto-recovery of port proxy services on startup\n- **📊 Health Monitoring**: Container status monitoring and instance details query\n- **📖 Swagger Documentation**: Complete API documentation with online testing support\n- **🔀 Multiple Load Balancing Strategies**: Round-robin, least connections, and weighted strategies\n\n## 🏗️ Architecture\n\nOneDock adopts a layered architecture with the following core components:\n\n- **API Layer** (`/api/`): RESTful route definitions and HTTP handlers\n- **Service Layer** (`/service/`): Core service management, Docker integration, and port management\n- **Model Layer** (`/models/`): Complete service data structures and API models\n- **Docker Client** (`/library/dockerclient/`): Docker operations abstraction layer\n- **Cache Layer** (`/library/cache/`): Memory and Redis cache implementations\n- **Utilities** (`/utils/`): Configuration management and common utilities\n\n### Intelligent Proxy System\n\nOneDock features an intelligent proxy system that automatically chooses the optimal proxying strategy:\n\n- **Single Replica Mode**: Uses `httputil.ReverseProxy` for direct proxying when `replicas = 1`\n- **Load Balancer Mode**: Automatically enables `LoadBalancer` when `replicas \u003e 1`\n- **Dynamic Switching**: Seamlessly switches between modes during scaling operations\n- **Access Consistency**: External access port remains unchanged regardless of replica count\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Go 1.24 or higher\n- Docker (must be accessible from the host system)\n- Git\n\n### ⚠️ Important Note on Deployment\n\n**OneDock should be deployed as a native binary on the host system, NOT as a Docker container.**\n\nSince OneDock is a Docker container orchestration service that needs to manage Docker containers, running it inside a Docker container would create unnecessary complexity and potential issues:\n\n- **Docker-in-Docker (DinD) complexity**: Requires complex volume mounts and privileged containers\n- **Network conflicts**: Port management and proxy functionality may conflict with container networking\n- **Security concerns**: Requires elevated privileges and Docker socket access\n- **Resource overhead**: Additional layer of containerization without benefits\n\n### Recommended Deployment Methods\n\n1. **Direct Binary Deployment** (Recommended)\n2. **Systemd Service** (For production environments)\n3. **Process Manager** (PM2, Supervisor, etc.)\n\n### Installation\n\n📖 **For detailed deployment instructions, see [Deploy Guide](./deploy/README.md)**\n\n#### Quick Installation\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/aichy126/onedock.git\ncd onedock\n\n# 2. Build the binary\ngo build -o onedock\n\n# 3. Install as systemd service (Linux)\nsudo ./deploy/install.sh\n```\n\n#### Manual Build and Run\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/aichy126/onedock.git\n   cd onedock\n   ```\n\n2. **Install dependencies**\n   ```bash\n   go mod tidy\n   ```\n\n3. **Configure the application**\n   ```bash\n   cp config.toml.example config.toml\n   # Edit config.toml according to your environment\n   ```\n\n4. **Run the development server**\n   ```bash\n   ./dev.sh\n   ```\n   Or run directly:\n   ```bash\n   go run main.go\n   ```\n\n5. **Access the API**\n   - API Base URL: `http://localhost:8801`\n   - Swagger UI: `http://localhost:8801/swagger/index.html`\n\n### Build for Production\n\n```bash\n# Build binary\ngo build -o onedock\n\n# Cross-compile for Linux\nCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o onedock-linux\n\n# Generate Swagger docs\nswag init\n```\n\n## 📖 API Documentation\n\n### Service Management\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/onedock/` | Deploy or update service |\n| `GET` | `/onedock/` | List all services |\n| `GET` | `/onedock/:name` | Get specific service details |\n| `DELETE` | `/onedock/:name` | Delete service |\n\n### Service Operations\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/onedock/:name/status` | Get detailed service status |\n| `POST` | `/onedock/:name/scale` | Scale service replicas |\n\n### Monitoring\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/onedock/ping` | Health check and debug info |\n| `GET` | `/onedock/proxy/stats` | Get port proxy statistics |\n\n## 💡 Usage Examples\n\n### Deploy a Service\n\n```bash\ncurl -X 'POST' 'http://127.0.0.1:8801/onedock' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"name\": \"nginx-web\",\n    \"image\": \"nginx\",\n    \"tag\": \"alpine\",\n    \"internal_port\": 80,\n    \"public_port\": 9203,\n    \"replicas\": 3,\n    \"environment\": {\n      \"ENV\": \"production\"\n    }\n  }'\n```\n\n### Scale a Service\n\n```bash\ncurl -X 'POST' 'http://127.0.0.1:8801/onedock/nginx-web/scale' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"replicas\": 5}'\n```\n\n### Get Service Status\n\n```bash\ncurl http://127.0.0.1:8801/onedock/nginx-web/status\n```\n\n### Access the Service\n\n```bash\ncurl http://localhost:9203/\n# Requests are automatically load-balanced across containers\n```\n\n## ⚙️ Configuration\n\nEdit `config.toml` to customize your deployment:\n\n```toml\n[local]\naddress = \":8801\"        # Service listen address\ndebug = true             # Gin debug mode\n\n[swaggerui]\nshow = true              # Show Swagger UI\nprotocol = \"http\"        # Protocol\nhost = \"127.0.0.1\"      # Host address\naddress = \":8801\"        # Port\n\n[container]\nprefix = \"onedock\"                    # Container name prefix\ninternal_port_start = 30000          # Internal port start value\ncache_ttl = 300                      # Cache expiration time (seconds)\nload_balance_strategy = \"round_robin\" # Load balancing strategy\n```\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run specific module tests\ngo test ./service/\ngo test ./library/cache/\ngo test ./library/dockerclient/\n\n# Run tests with coverage\ngo test -cover ./...\n```\n\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Gin](https://github.com/gin-gonic/gin) - HTTP web framework\n- [Docker](https://www.docker.com/) - Containerization platform\n- [Swagger](https://swagger.io/) - API documentation\n\n## 📞 Support\n\n- 🐛 Issues: [GitHub Issues](https://github.com/aichy126/onedock/issues)\n- 💬 Discussions: [GitHub Discussions](https://github.com/aichy126/onedock/discussions)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faichy126%2Fonedock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faichy126%2Fonedock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faichy126%2Fonedock/lists"}