{"id":30713279,"url":"https://github.com/clement-tourriere/devproxy","last_synced_at":"2026-05-07T04:42:30.611Z","repository":{"id":312864645,"uuid":"1048667259","full_name":"clement-tourriere/devproxy","owner":"clement-tourriere","description":"Zero-config HTTPS proxy for Docker containers","archived":false,"fork":false,"pushed_at":"2025-09-02T12:19:10.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T14:26:19.660Z","etag":null,"topics":["development","docker","docker-compose","domains","https"],"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/clement-tourriere.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T20:30:54.000Z","updated_at":"2025-09-02T12:19:13.000Z","dependencies_parsed_at":"2025-09-02T17:31:25.070Z","dependency_job_id":null,"html_url":"https://github.com/clement-tourriere/devproxy","commit_stats":null,"previous_names":["clement-tourriere/devproxy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/clement-tourriere/devproxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clement-tourriere%2Fdevproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clement-tourriere%2Fdevproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clement-tourriere%2Fdevproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clement-tourriere%2Fdevproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clement-tourriere","download_url":"https://codeload.github.com/clement-tourriere/devproxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clement-tourriere%2Fdevproxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273386851,"owners_count":25096248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"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":["development","docker","docker-compose","domains","https"],"created_at":"2025-09-03T03:45:10.822Z","updated_at":"2026-05-07T04:42:30.595Z","avatar_url":"https://github.com/clement-tourriere.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DevProxy 🚀\n\n**Zero-config HTTPS proxy for Docker containers**\n\nDevProxy automatically provides HTTPS access to all your Docker containers at predictable URLs, just like Orbstack's container domains feature. No configuration required!\n\n## ✨ Features\n\n- 🔧 **Zero Configuration**: No labels, env vars, or setup needed\n- 🌐 **Automatic HTTPS**: Local CA with automatic certificate generation\n- 📋 **Predictable URLs**: `https://container_name.localhost` and `https://service.project_name.localhost`\n- 🔄 **Real-time Discovery**: Automatically detects container start/stop events\n- 🎯 **Smart Port Detection**: Uses exposed ports or common web ports (80, 8080, 3000, 8000, 5000)\n- 🛡️ **Container IP Support**: Direct routing without port mapping\n- ⚙️ **Optional Overrides**: Custom domains and ports when needed\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker and Docker Compose\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/clement-tourriere/devproxy\n   cd devproxy\n   ```\n\n2. **Start DevProxy**\n   ```bash\n   docker compose up -d\n   ```\n\n3. **Test it works**\n   ```bash\n   # Create a test container\n   docker run -d --name test-nginx nginx:alpine\n\n   # Visit https://test-nginx.localhost in your browser\n   # You should see the nginx welcome page with HTTPS!\n   ```\n\n4. **Install trusted certificates (optional but recommended)**\n   ```bash\n   # Run the certificate installer\n   ./trust-cert.sh\n\n   # Restart your browser\n   # Now visit https://test-nginx.localhost - no more security warnings!\n   ```\n\nThat's it! 🎉\n\n\u003e **📱 macOS DNS Note**: `*.localhost` domains work in browsers (Chrome, Firefox, Safari) and curl, but may not work in all CLI tools or applications. For broader compatibility, consider adding entries to `/etc/hosts`.\n\n## 🔒 HTTPS Certificate Setup\n\nDevProxy uses Caddy's local Certificate Authority (CA) to provide automatic HTTPS. By default, browsers will show security warnings because the CA isn't trusted by your system.\n\n### Automatic Certificate Installation\n\nRun the included script to install DevProxy's root certificate in your system trust store:\n\n```bash\n./trust-cert.sh\n```\n\nThis script works on:\n- **macOS**: Installs certificate in System Keychain\n- **Linux**: Supports Debian/Ubuntu (`update-ca-certificates`), RHEL/Fedora (`update-ca-trust`), and p11-kit\n- **Windows**: Uses `certutil` (run from Administrator Command Prompt)\n\nAfter installation:\n1. Restart your browser\n2. Visit any DevProxy domain - no more security warnings!\n3. The dashboard will automatically use HTTPS links\n\n### Manual Certificate Installation\n\nIf the automatic script doesn't work for your system:\n\n1. **Export the certificate**:\n   ```bash\n   docker exec devproxy-caddy cat /data/caddy/pki/authorities/local/root.crt \u003e caddy-root.crt\n   ```\n\n2. **Install in your system** (varies by OS - consult your system documentation)\n\n3. **Restart your browser**\n\n### HTTP Fallback\n\nIf you prefer not to install certificates, DevProxy automatically detects when certificates aren't trusted and provides HTTP links in the dashboard instead.\n\n## 🆚 Why DevProxy?\n\nDevProxy brings OrbStack's beloved container domains feature to any Docker setup:\n\n| Feature | DevProxy | Manual nginx/traefik | Port Mapping |\n|---------|----------|---------------------|--------------|\n| **Setup** | Zero config | Complex configuration | Manual port assignment |\n| **URLs** | `app.localhost` | Custom domain setup | `localhost:8080` |\n| **HTTPS** | Automatic with local CA | Manual cert management | None |\n| **Discovery** | Real-time container events | Manual service registration | Manual |\n| **Multi-project** | Automatic namespacing | Complex routing rules | Port conflicts |\n\n## 📖 How It Works\n\nDevProxy consists of two main components:\n\n1. **DevProxy Manager**: Monitors Docker events and manages container discovery\n2. **Caddy Proxy**: Handles HTTPS termination and reverse proxying\n\n### Domain Mapping Rules\n\n| Container Type | Domain Format | Example |\n|---------------|---------------|---------|\n| Standalone Container | `container_name.localhost` | `nginx.localhost` |\n| Compose Service | `service.project_name.localhost` | `web.myapp.localhost` |\n| Custom Override | `devproxy.domain` label | `api.example.localhost` |\n\n### Port Detection Priority\n\n1. `DEVPROXY_PORT` environment variable\n2. `devproxy.port` label\n3. First exposed port in container\n4. Common web ports: 80, 8080, 3000, 8000, 5000\n\n### Performance \u0026 Resource Usage\n\nDevProxy is designed to be lightweight and efficient:\n- **Minimal overhead**: Uses Docker's event stream for real-time updates\n- **Low memory**: \u003c 20MB RAM usage for both DevProxy and Caddy combined\n- **Fast startup**: \u003c 2 seconds to fully initialize and proxy containers\n- **Container IP routing**: Direct connection to containers, no port mapping bottleneck\n\n## 🛠️ Usage Examples\n\n### Basic Usage\n\n```bash\n# Start any container - it's automatically available via HTTPS\ndocker run -d --name my-app nginx:alpine\n# → Available at https://my-app.localhost\n```\n\n### Docker Compose\n\n```yaml\n# compose.yaml\nservices:\n  web:\n    image: nginx:alpine\n  api:\n    image: node:alpine\n    command: node server.js\n\n# Run: docker compose up -d\n# → web: https://web.myproject.localhost\n# → api: https://api.myproject.localhost\n# → project: https://myproject.localhost\n```\n\n### Custom Configuration\n\n```bash\n# Custom port via environment variable\ndocker run -d --name my-api -e DEVPROXY_PORT=3000 node:alpine\n\n# Custom port via label\ndocker run -d --name my-api --label devproxy.port=3000 node:alpine\n\n# Custom domain via label\ndocker run -d --name my-api --label devproxy.domain=api.mycompany.localhost node:alpine\n\n# Disable proxy for a container\ndocker run -d --name utility --label devproxy.enabled=false alpine sleep 3600\n```\n\n## 🎛️ Dashboard\n\nDevProxy includes a web dashboard to view all active container domains:\n\n**📍 Dashboard URL**: `https://devproxy-dashboard.localhost`\n\nThe dashboard shows:\n- All active containers and their domains\n- Container status and ports\n- Quick links to access services\n- Real-time updates when containers start/stop\n\n## 🔧 Development Setup\n\n### Prerequisites\n\n```bash\n# Install mise for Go version management\ncurl https://mise.run | sh\n```\n\n```bash\n# Initialize mise\n# Trust mise\nmise trust\nmise install\n```\n\n### Build from Source\n\n```bash\n\n# Install dependencies\ngo mod tidy\n\n# Build binary\ngo build -o devproxy ./cmd/devproxy\n\n# Build Docker image\ndocker compose build\n```\n\n### Project Structure\n\n```\ndevproxy/\n├── cmd/\n│   ├── devproxy/          # Main DevProxy application\n│   └── dashboard/         # Dashboard application\n├── internal/\n│   ├── docker/            # Docker API integration \u0026 discovery\n│   ├── caddy/             # Caddy configuration \u0026 API client\n│   ├── proxy/             # Main orchestration logic\n│   └── dashboard/         # Web dashboard server\n├── compose.yaml           # Docker Compose setup\n├── Dockerfile            # DevProxy container image\n├── Dockerfile.dashboard   # Dashboard container image\n├── Caddyfile             # Initial Caddy configuration\n├── trust-cert.sh         # Certificate installation script\n├── INSTALL.md            # Installation guide\n├── CLAUDE.md             # Development documentation\n└── README.md            # This file\n```\n\n## ⚙️ Configuration\n\nDevProxy works perfectly without any configuration, but offers flexible customization options when needed.\n\n### 🎛️ DevProxy Configuration\n\n| Environment Variable | Description | Default | Example |\n|---------------------|-------------|---------|---------|\n| `DEVPROXY_LOG_LEVEL` | Logging verbosity (debug/info/warn/error) | `info` | `debug` |\n| `DEVPROXY_DOMAIN_SUFFIX` | Domain suffix for containers | `localhost` | `dev.local` |\n| `CADDY_ADMIN_URL` | Caddy admin API URL | `http://caddy:2019` | `http://localhost:2019` |\n\n### 📊 Dashboard Configuration\n\n| Environment Variable | Description | Default | Example |\n|---------------------|-------------|---------|---------|\n| `DEVPROXY_DASHBOARD_REFRESH` | Auto-refresh interval (seconds) | `30` | `10` |\n| `DEVPROXY_DASHBOARD_EXCLUDE` | Projects to hide (comma-separated) | `devproxy` | `devproxy,test,staging` |\n| `DEVPROXY_DASHBOARD_SHOW_ALL` | Show all containers including system ones | `false` | `true` |\n| `DASHBOARD_ADDR` | Dashboard listening address | `:8080` | `:3000` |\n\n### 🏷️ Container Labels\n\n| Label | Description | Example |\n|-------|-------------|---------|\n| `devproxy.enabled` | Enable/disable proxy | `false` |\n| `devproxy.domain` | Custom domain | `api.mycompany.localhost` |\n| `devproxy.port` | Custom port | `3000` |\n\n### 📝 Usage Examples\n\n#### Default (Zero Configuration)\n```bash\ndocker compose up -d\n# Works perfectly with sensible defaults\n```\n\n#### Custom Dashboard Refresh Rate\n```bash\n# Dashboard updates every 10 seconds instead of 30\nDEVPROXY_DASHBOARD_REFRESH=10 docker compose up -d\n```\n\n#### Show All Containers in Dashboard\n```bash\n# Include DevProxy's own containers in dashboard\nDEVPROXY_DASHBOARD_SHOW_ALL=true docker compose up -d\n```\n\n#### Hide Multiple Projects\n```bash\n# Hide development and test projects from dashboard\nDEVPROXY_DASHBOARD_EXCLUDE=devproxy,test,staging docker compose up -d\n```\n\n#### Debug Logging\n```bash\n# Enable detailed debug logging\nDEVPROXY_LOG_LEVEL=debug docker compose up -d\n```\n\n#### Using .env File (Recommended)\nCreate a `.env` file in your DevProxy directory:\n```bash\n# .env\nDEVPROXY_LOG_LEVEL=debug\nDEVPROXY_DASHBOARD_REFRESH=15\nDEVPROXY_DASHBOARD_EXCLUDE=devproxy,internal\nDEVPROXY_DASHBOARD_SHOW_ALL=false\n```\n\nThen start normally:\n```bash\ndocker compose up -d\n```\n\n#### Per-Container Configuration\n```bash\n# Custom port via environment variable\ndocker run -d --name my-api -e DEVPROXY_PORT=3000 node:alpine\n\n# Custom port via label\ndocker run -d --name my-api --label devproxy.port=3000 node:alpine\n\n# Custom domain via label\ndocker run -d --name my-api --label devproxy.domain=api.mycompany.localhost node:alpine\n\n# Disable proxy for a container\ndocker run -d --name utility --label devproxy.enabled=false alpine sleep 3600\n```\n\n## ⚠️ Important Limitations\n\n### Container-to-Container Communication\n\n**`.localhost` domains do NOT work for container-to-container communication** because they resolve to 127.0.0.1 inside containers.\n\n**✅ What works:**\n- **Browser/Host access**: `https://myapp.localhost` ✅\n- **Container-to-container via container names**: `http://myapp` ✅  \n- **Container-to-container via IPs**: `http://172.18.0.3` ✅\n\n**❌ What doesn't work:**\n- **Container-to-container via .localhost**: `http://myapp.localhost` ❌ (resolves to 127.0.0.1)\n\n### Docker Environment Compatibility\n\n**✅ Works with:**\n- Docker Engine on Linux\n- Docker Desktop on macOS (in most configurations)\n- Any environment where containers get individual IP addresses\n\n**❌ May not work with:**\n- Docker Desktop with certain network configurations\n- Environments where containers share the host network\n- Systems where container IPs are not directly routable\n\n### DNS Setup (Optional)\n\nFor `*.localhost` domains to work system-wide in all applications:\n\n**macOS/Linux**:\n```bash\n# Add to /etc/hosts (requires sudo)\n127.0.0.1 myapp.localhost\n127.0.0.1 devproxy-dashboard.localhost\n\n# Or use dnsmasq for wildcard support\nbrew install dnsmasq\necho 'address=/localhost/127.0.0.1' \u003e /usr/local/etc/dnsmasq.conf\nsudo brew services start dnsmasq\n```\n\n**Windows**:\n```powershell\n# Add to C:\\Windows\\System32\\drivers\\etc\\hosts\n127.0.0.1 myapp.localhost\n127.0.0.1 devproxy-dashboard.localhost\n```\n\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n**Container not accessible**\n```bash\n# Check if DevProxy is running\ndocker compose ps\n\n# Check logs\ndocker compose logs devproxy\ndocker compose logs caddy\n\n# Verify container has correct IP\ndocker inspect \u003ccontainer_name\u003e | grep IPAddress\n```\n\n**HTTPS Certificate Issues**\n```bash\n# Restart DevProxy to regenerate certificates\ndocker compose restart\n\n# Check Caddy certificate status\ndocker compose exec caddy caddy trust\n```\n\n**HTTPS stopped working after removing volumes**\n```bash\n# If you ran: docker compose down -v\n# This removes Caddy's certificate volumes, generating new certificates\n\n# Solution: Re-trust the new certificates\n./trust-cert.sh\n\n# Then restart your browser to use the new trusted certificates\n```\n\n**Port Detection Issues**\n```bash\n# Override port manually\ndocker run -d --name myapp -e DEVPROXY_PORT=8080 myimage\n\n# Or use label\ndocker run -d --name myapp --label devproxy.port=8080 myimage\n```\n\n### Logs and Debugging\n\n```bash\n# View all logs\ndocker compose logs\n\n# Follow DevProxy manager logs\ndocker compose logs -f devproxy\n\n# Follow Caddy proxy logs\ndocker compose logs -f caddy\n\n# Debug specific container\ndocker logs \u003ccontainer_name\u003e\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests if applicable\n5. Commit: `git commit -am 'Add feature'`\n6. Push: `git push origin feature-name`\n7. Create a Pull Request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by [Orbstack's](https://orbstack.dev) container domains feature\n- Built with [Caddy](https://caddyserver.com/) for automatic HTTPS\n- Uses Docker API for container discovery\n\n---\n\n**🌟 Star this repo if DevProxy helps you!**\n\nNeed help? Open an issue or join our discussions!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclement-tourriere%2Fdevproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclement-tourriere%2Fdevproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclement-tourriere%2Fdevproxy/lists"}