{"id":25519600,"url":"https://github.com/amhoba/docker-compose-local-development-port-mapper","last_synced_at":"2026-01-27T08:03:33.485Z","repository":{"id":264243271,"uuid":"892806816","full_name":"amhoba/docker-compose-local-development-port-mapper","owner":"amhoba","description":"🚀 A lightweight port mapping proxy tool that enables local development while keeping resource-intensive services on remote servers.","archived":false,"fork":false,"pushed_at":"2024-11-23T16:47:26.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-04T02:43:42.434Z","etag":null,"topics":["container","developer-tools","development-tools","devops","docker","docker-compose","local-development","microservices","port-forwarding","proxy","remote-development","ssh","ssh-tunnel"],"latest_commit_sha":null,"homepage":"","language":"Python","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/amhoba.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}},"created_at":"2024-11-22T20:20:06.000Z","updated_at":"2024-11-23T16:47:30.000Z","dependencies_parsed_at":"2025-02-14T17:58:36.279Z","dependency_job_id":"d0297e77-fe22-4f52-a40a-1fd5f129416d","html_url":"https://github.com/amhoba/docker-compose-local-development-port-mapper","commit_stats":null,"previous_names":["amhoba2014/docker-compose-local-development-port-mapper","amhoba/docker-compose-local-development-port-mapper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/amhoba/docker-compose-local-development-port-mapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amhoba%2Fdocker-compose-local-development-port-mapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amhoba%2Fdocker-compose-local-development-port-mapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amhoba%2Fdocker-compose-local-development-port-mapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amhoba%2Fdocker-compose-local-development-port-mapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amhoba","download_url":"https://codeload.github.com/amhoba/docker-compose-local-development-port-mapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amhoba%2Fdocker-compose-local-development-port-mapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28809337,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T07:41:26.337Z","status":"ssl_error","status_checked_at":"2026-01-27T07:41:08.776Z","response_time":168,"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","developer-tools","development-tools","devops","docker","docker-compose","local-development","microservices","port-forwarding","proxy","remote-development","ssh","ssh-tunnel"],"created_at":"2025-02-19T17:20:21.185Z","updated_at":"2026-01-27T08:03:33.469Z","avatar_url":"https://github.com/amhoba.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker Compose Local Development Port Mapper\n\nA simple yet powerful solution to streamline local development while keeping heavy services on remote servers. This project creates lightweight Docker proxy images that forward traffic to remote services via SSH. Ideal for scenarios where you want to develop locally but use resource-intensive services like databases, ELK stacks, or other backend services hosted remotely.\n\n## 🚀 Overview\n\nThis tool solves a common challenge in microservices development: the need to have instant **feedback loop** and run **resource-intensive services** locally at the same time. Instead of running heavy services like ELK Stack, databases, or machine learning models on your development machine, this tool creates lightweight proxy containers that forward traffic to the actual services running on a remote server.\n\n## 🔑 Key Benefits\n\n- 🔥 Dramatically reduced local resource usage.\n- 🚄 Faster local development setup and ⚡️ instant feedback loop.\n- 💻 Work with production-like environments locally (mostly **staging** environments).\n- 🔒 Secure SSH-based communication.\n- 🔌 Seamless integration with existing docker compose files.\n\n## 🛠 How It Works\n\nThe tool creates a proxy Docker image that replaces the actual service image in your local docker compose file.\n\nWhen the proxy container starts, it:\n\n- Establishes an SSH connection to the remote server.\n- Identifies the target service container on the remote server.\n- Sets up port forwarding from your local machine to the remote container.\n- Maintains the SSH connection for the duration of the container's life.\n\n## 📋 Prerequisites\n\n- Docker and Docker Compose installed locally.\n- SSH access to the remote server.\n- Docker and Docker Compose running on the remote server.\n\n## 🔧 Installation\n\n1. Clone this repository:\n\n```bash\ngit clone https://github.com/amhoba2014/docker-compose-local-development-port-mapper\ncd docker-compose-local-development-port-mapper\n```\n\n2. Generate and copy your SSH key:\n\n```bash\ncp /path/to/your/existing/ssh/key ./assets/ssh_key\n```\n\n3. Set proper permissions:\n\n```bash\nchmod 600 ./assets/ssh_key\n```\n\n4. Configure your remote server settings:\n\n- `REMOTE_USER`: Username of the remote server that SSH key is created for.\n- `REMOTE_IP`: IP address of the remote server.\n- `REMOTE_PATH`: Path on the remote server to the directory containing the *docker-compose.yml*.\n- `REMOTE_BASE_COMPOSE_COMMAND`: The base *docker compose* command that is used on remote server to spin up containers.\n\n```bash\nnano ./assets/configuration.py\n```\n\n## 📝 Usage\n\n1. Build the image:\n\n```bash\ncd docker-compose-local-development-port-mapper\nbash build.sh\n```\n\n2. Modify your local `docker-compose.yml`:\n\nReplace the original service images with the port mapper image:\n\n```yaml\nservices:\n  heavy_service:\n    image: port_mapper:latest\n    environment:\n      - SERVICE_NAME=heavy_service\n      - SERVICE_PORT=8080\n```\n\n3. Start your development environment:\n\n```bash\ndocker compose up\n```\n\n## 🌟 Example\n\nConverting an ELK stack service to use port mapping:\n\n### Original service:\n\nThis is part of a bigger `docker-compose.yml` file running on a **dev** or **staging** server.\n\n```yaml\nelasticsearch:\n  build:\n    context: ../elasticsearch\n    target: dev\n  ports:\n    - \"9200:9200\"\n```\n\n### With port mapper:\n\nThis is part of our local `docker-compose.yml` file, shall run locally.\n\n```yaml\nelasticsearch:\n  image: port_mapper:latest\n  environment:\n    - SERVICE_NAME=elasticsearch\n    - SERVICE_PORT=9200\n```\n\n## 🔐 Security Considerations\n\n1. Never commit SSH keys to version control and use this project locally and share it with colleagues over a trusted wire (USB drive or local network).\n2. Use dedicated keys for the port mapper.\n3. Regularly rotate SSH keys.\n\n## 🚧 Limitations\n\n- Works only with **docker compose** based setups (which I know most organisations do not use them in staging). Can be tweaked to support **Kubernetes** and **VPC** (GCP, AWS, Azure) based setups.\n- A slight latency, dependent on the network connection type.\n- Requires high speed and stable internet connection (optic fiber works best).\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n# 👏 Acknowledgments\n\nInspired by the need for efficient local development at my previous job.\n\nThis is more like a SRE/DevOps tooling and type of work, which I almost do most of the times for both myself and my colleagues.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famhoba%2Fdocker-compose-local-development-port-mapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famhoba%2Fdocker-compose-local-development-port-mapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famhoba%2Fdocker-compose-local-development-port-mapper/lists"}