{"id":26730320,"url":"https://github.com/webproject-xyz/docker-hosts-file-sync","last_synced_at":"2026-05-15T04:35:36.240Z","repository":{"id":284624172,"uuid":"951512133","full_name":"WebProject-xyz/docker-hosts-file-sync","owner":"WebProject-xyz","description":"A PHP docker API client and with a cli tool to sync your hosts file with running docker containers to add hostnames and network aliases","archived":false,"fork":false,"pushed_at":"2025-09-29T05:59:04.000Z","size":1106,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-29T07:23:38.555Z","etag":null,"topics":["cli","cli-application","docker-api","docker-container","hosts","hostsfile","php","php-docker-api","php-docker-api-client","sync"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/WebProject-xyz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-03-19T19:49:56.000Z","updated_at":"2025-09-29T05:59:07.000Z","dependencies_parsed_at":"2025-04-10T08:24:32.406Z","dependency_job_id":"bae69969-4300-499b-a6f8-9eab592d1948","html_url":"https://github.com/WebProject-xyz/docker-hosts-file-sync","commit_stats":null,"previous_names":["webproject-xyz/docker-hosts-file-sync"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/WebProject-xyz/docker-hosts-file-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebProject-xyz%2Fdocker-hosts-file-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebProject-xyz%2Fdocker-hosts-file-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebProject-xyz%2Fdocker-hosts-file-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebProject-xyz%2Fdocker-hosts-file-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebProject-xyz","download_url":"https://codeload.github.com/WebProject-xyz/docker-hosts-file-sync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebProject-xyz%2Fdocker-hosts-file-sync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279011295,"owners_count":26084928,"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-10-12T02:00:06.719Z","response_time":53,"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":["cli","cli-application","docker-api","docker-container","hosts","hostsfile","php","php-docker-api","php-docker-api-client","sync"],"created_at":"2025-03-27T23:19:18.911Z","updated_at":"2026-05-15T04:35:36.220Z","avatar_url":"https://github.com/WebProject-xyz.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker Hosts File Sync\n\n[![CI](https://github.com/WebProject-xyz/docker-hosts-file-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/WebProject-xyz/docker-hosts-file-sync/actions/workflows/ci.yml)\n[![Release](https://github.com/WebProject-xyz/docker-hosts-file-sync/actions/workflows/release.yml/badge.svg)](https://github.com/WebProject-xyz/docker-hosts-file-sync/actions/workflows/release.yml)\n[![Docker Image](https://github.com/WebProject-xyz/docker-hosts-file-sync/actions/workflows/build-docker-image.yml/badge.svg)](https://github.com/WebProject-xyz/docker-hosts-file-sync/actions/workflows/build-docker-image.yml)\n[![PHP Version](https://img.shields.io/packagist/php-v/webproject-xyz/docker-hostsfile-sync)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)\n[![Latest Stable Version](https://img.shields.io/packagist/v/webproject-xyz/docker-hostsfile-sync)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)\n[![Total Downloads](https://img.shields.io/packagist/dt/webproject-xyz/docker-hostsfile-sync)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)\n[![License](https://img.shields.io/packagist/l/webproject-xyz/docker-hostsfile-sync)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)\n\nAutomatically sync your `/etc/hosts` file with running Docker containers. Each container gets hostnames for every network it's connected to.\n\n\u003e Inspired by [docker-hostmanager](https://github.com/iamluc/docker-hostmanager)\n\n## Features\n\n- Listens to Docker events in real-time (start, stop, restart)\n- Generates hostnames based on container name and network\n- Supports reverse proxy setups (nginx-proxy, Traefik, etc.)\n- Reads hostnames from `DOMAIN_NAME` and `VIRTUAL_HOST` environment variables\n- Works with Docker and Podman\n\n## Quick Start\n\n### Using Docker (Recommended)\n\n```bash\ndocker run -d \\\n  --name docker-hostfile-sync \\\n  --restart=always \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  -v /etc/hosts:/app/hosts \\\n  ghcr.io/webproject-xyz/docker-hosts-file-sync:latest\n```\n\n### Using Docker Compose\n\n```yaml\nservices:\n  docker-hostfile-sync:\n    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest\n    container_name: docker-hostfile-sync\n    restart: always\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /etc/hosts:/app/hosts\n```\n\n```bash\ndocker compose up -d\n```\n\n## Configuration\n\n### Command Line Options\n\n| Option                     | Short | Description                       | Default       |\n|----------------------------|-------|-----------------------------------|---------------|\n| `--hosts_file`             | `-f`  | Path to hosts file                | `./tmp-hosts` |\n| `--tld`                    | `-t`  | TLD suffix for hostnames          | `.docker`     |\n| `--reverse-proxy-host-ip`  | `-r`  | IP address of your reverse proxy  | -             |\n\n### Environment Variables\n\nYou can also configure via environment variables:\n\n| Variable     | Description                      |\n|--------------|----------------------------------|\n| `HOSTS_FILE` | Path to hosts file               |\n| `TLD`        | TLD suffix for hostnames         |\n\n## Examples\n\n### Example 1: Basic Setup\n\nA simple web application with a database:\n\n```yaml\n# docker-compose.yml\nservices:\n  docker-hostfile-sync:\n    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest\n    restart: always\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /etc/hosts:/app/hosts\n\n  webapp:\n    image: nginx:alpine\n    container_name: webapp\n\n  database:\n    image: mysql:8\n    container_name: database\n```\n\n**Generated hosts entries:**\n\n```text\n## docker-hostsfile-sync\n172.20.0.2 webapp.docker webapp.myproject_default\n172.20.0.3 database.docker database.myproject_default\n## docker-hostsfile-sync-end\n```\n\nNow you can access your services:\n- `http://webapp.docker` → nginx container\n- `mysql -h database.docker` → MySQL container\n\n---\n\n### Example 2: Multiple Networks\n\nWhen containers are connected to multiple networks, each network gets its own hostname:\n\n```yaml\n# docker-compose.yml\nservices:\n  docker-hostfile-sync:\n    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest\n    restart: always\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /etc/hosts:/app/hosts\n\n  webapp:\n    image: nginx:alpine\n    container_name: webapp\n    networks:\n      - frontend\n      - backend\n\n  api:\n    image: node:alpine\n    container_name: api\n    networks:\n      - backend\n\n  database:\n    image: postgres:16\n    container_name: database\n    networks:\n      - backend\n\nnetworks:\n  frontend:\n  backend:\n```\n\n**Generated hosts entries:**\n\n```text\n## docker-hostsfile-sync\n172.21.0.2 webapp.docker webapp.frontend\n172.22.0.2 webapp.backend\n172.22.0.3 api.docker api.backend\n172.22.0.4 database.docker database.backend\n## docker-hostsfile-sync-end\n```\n\nThis allows:\n- Frontend services reach `webapp` via `webapp.frontend`\n- Backend services communicate via `*.backend` hostnames\n- Your host machine can reach any container directly\n\n---\n\n### Example 3: With Reverse Proxy (nginx-proxy)\n\nFor production-like setups with a reverse proxy, use the `--reverse-proxy-host-ip` option. This routes URL-like hostnames (containing dots) to your proxy:\n\n```yaml\n# docker-compose.yml\nservices:\n  docker-hostfile-sync:\n    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest\n    restart: always\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /etc/hosts:/app/hosts\n    command: --reverse-proxy-host-ip=172.16.238.100\n\n  nginx-proxy:\n    image: nginxproxy/nginx-proxy\n    container_name: nginx-proxy\n    ports:\n      - \"80:80\"\n    volumes:\n      - /var/run/docker.sock:/tmp/docker.sock:ro\n    networks:\n      proxy:\n        ipv4_address: 172.16.238.100\n\n  webapp:\n    image: nginx:alpine\n    container_name: webapp\n    environment:\n      - VIRTUAL_HOST=webapp.local,www.webapp.local\n    networks:\n      - proxy\n      - default\n\n  api:\n    image: node:alpine\n    container_name: api\n    environment:\n      - DOMAIN_NAME=api.local\n    networks:\n      proxy:\n        aliases:\n          - api.dev.local\n      default:\n\nnetworks:\n  proxy:\n    ipam:\n      config:\n        - subnet: 172.16.238.0/24\n```\n\n**Generated hosts entries:**\n\n```text\n## docker-hostsfile-sync\n# nginx-proxy container\n172.16.238.100 nginx-proxy.docker nginx-proxy.proxy\n\n# webapp container - direct access via container IP\n172.20.0.2 webapp.docker webapp.myproject_default\n172.16.238.2 webapp.proxy\n\n# webapp container - reverse proxy routes (from VIRTUAL_HOST env var)\n172.16.238.100 webapp.local www.webapp.local\n\n# api container - direct access\n172.20.0.3 api.docker api.myproject_default\n172.16.238.3 api.proxy\n\n# api container - reverse proxy routes (from DOMAIN_NAME env var and network alias)\n172.16.238.100 api.dev.local api.local\n## docker-hostsfile-sync-end\n```\n\nNow you can:\n- Access `http://webapp.local` → routed through nginx-proxy to webapp\n- Access `http://api.local` → routed through nginx-proxy to api\n- Access `http://webapp.proxy` → direct to webapp container (bypassing proxy)\n- Debug with `http://api.docker` → direct container access\n\n---\n\n### Example 4: Network Aliases\n\nNetwork aliases let you give containers additional hostnames. Aliases containing a dot (`.`) are treated as URLs and routed to the reverse proxy:\n\n```yaml\nservices:\n  docker-hostfile-sync:\n    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest\n    restart: always\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n      - /etc/hosts:/app/hosts\n    command: --reverse-proxy-host-ip=172.16.238.100\n\n  webapp:\n    image: nginx:alpine\n    container_name: webapp\n    networks:\n      default:\n        aliases:\n          - frontend          # Simple alias → webapp IP\n          - app.example.com   # URL-like alias → reverse proxy IP\n```\n\n**Generated hosts entries:**\n\n```text\n## docker-hostsfile-sync\n172.20.0.2 webapp.docker frontend.default webapp.default\n172.16.238.100 app.example.com\n## docker-hostsfile-sync-end\n```\n\n## How It Works\n\nThe tool manages a section in your hosts file between these markers:\n\n```text\n## docker-hostsfile-sync\n...entries managed automatically...\n## docker-hostsfile-sync-end\n```\n\nEverything outside these markers is left untouched.\n\n### Hostname Generation Rules\n\n| Source | Example | Generated Hostname | Target IP |\n|--------|---------|-------------------|-----------|\n| Container name | `webapp` | `webapp.networkname` | Container IP |\n| Simple network alias | `frontend` | `frontend.networkname` | Container IP |\n| URL-like network alias | `app.example.com` | `app.example.com` | Reverse proxy IP |\n| `DOMAIN_NAME` env var | `api.local` | `api.local` | Reverse proxy IP |\n| `VIRTUAL_HOST` env var | `www.app.local` | `www.app.local` | Reverse proxy IP |\n\n**URL-like aliases** (containing a `.`) are assumed to be real domain names that should route through your reverse proxy. **Simple aliases** (no `.`) are combined with the network name.\n\n## Running Locally (Development)\n\n```bash\n# Install dependencies\ncomposer install\n\n# Run (outputs to ./tmp-hosts for testing)\nphp bin/docker-api synchronize-hosts -v\n\n# Run with reverse proxy support\nphp bin/docker-api synchronize-hosts -v --reverse-proxy-host-ip=172.16.238.100\n\n# Run targeting /etc/hosts (requires sudo)\nsudo php bin/docker-api synchronize-hosts --hosts_file=/etc/hosts -v\n\n# View logs\ndocker compose logs -f docker-hostfile-sync\n```\n\n## Troubleshooting\n\n### Hosts file not updating\n\n1. Check the container has write access to the hosts file:\n   ```bash\n   docker exec docker-hostfile-sync ls -la /app/hosts\n   ```\n\n2. Check logs for errors:\n   ```bash\n   docker logs docker-hostfile-sync\n   ```\n\n### Container not appearing in hosts file\n\nContainers must be \"exposed\" (have at least one network with an IP address). Check your container:\n\n```bash\ndocker inspect \u003ccontainer_name\u003e --format '{{json .NetworkSettings.Networks}}'\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebproject-xyz%2Fdocker-hosts-file-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebproject-xyz%2Fdocker-hosts-file-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebproject-xyz%2Fdocker-hosts-file-sync/lists"}