PHPackages                             webproject-xyz/docker-hostsfile-sync - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. webproject-xyz/docker-hostsfile-sync

ActiveProject[CLI & Console](/categories/cli)

webproject-xyz/docker-hostsfile-sync
====================================

A PHP docker API client with a cli tool to sync your hosts file with running docker containers to add hostnames for every network like '172.16.238.100 jwilder-proxy.docker jwilder-proxy.proxyNet jwilder.proxyNet proxy.local.proxyNet'

1.8.3(1w ago)10[1 issues](https://github.com/WebProject-xyz/docker-hosts-file-sync/issues)[4 PRs](https://github.com/WebProject-xyz/docker-hosts-file-sync/pulls)MITPHPPHP ~8.5.0CI passing

Since Mar 19Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/WebProject-xyz/docker-hosts-file-sync)[ Packagist](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)[ Docs](https://www.webproject.xyz)[ RSS](/packages/webproject-xyz-docker-hostsfile-sync/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (61)Versions (36)Used By (0)

Docker Hosts File Sync
======================

[](#docker-hosts-file-sync)

[![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)[![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)[![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)[![PHP Version](https://camo.githubusercontent.com/8f8d2a105c955e92c07e52705834ea28c53623c3a65e08e30846801a45089e79/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f77656270726f6a6563742d78797a2f646f636b65722d686f73747366696c652d73796e63)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)[![Latest Stable Version](https://camo.githubusercontent.com/61a919cda8d77d7f98a5b80e07db9fea78376073ba2bcae2b5f9b045d25b86d2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f77656270726f6a6563742d78797a2f646f636b65722d686f73747366696c652d73796e63)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)[![Total Downloads](https://camo.githubusercontent.com/c82337e78698f91762258db74661316423a036b8f5f6f2f2dfd3dfccb0a503ca/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f77656270726f6a6563742d78797a2f646f636b65722d686f73747366696c652d73796e63)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)[![License](https://camo.githubusercontent.com/abceaf134072779ef3af9d96a535388e42c7699949859625563ff4031f1a96dc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f77656270726f6a6563742d78797a2f646f636b65722d686f73747366696c652d73796e63)](https://packagist.org/packages/webproject-xyz/docker-hostsfile-sync)

Automatically sync your `/etc/hosts` file with running Docker containers. Each container gets hostnames for every network it's connected to.

> Inspired by [docker-hostmanager](https://github.com/iamluc/docker-hostmanager)

Features
--------

[](#features)

- Listens to Docker events in real-time (start, stop, restart)
- Generates hostnames based on container name and network
- Supports reverse proxy setups (nginx-proxy, Traefik, etc.)
- Reads hostnames from `DOMAIN_NAME` and `VIRTUAL_HOST` environment variables
- Works with Docker and Podman

Quick Start
-----------

[](#quick-start)

### Using Docker (Recommended)

[](#using-docker-recommended)

```
docker run -d \
  --name docker-hostfile-sync \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/hosts:/app/hosts \
  ghcr.io/webproject-xyz/docker-hosts-file-sync:latest
```

### Using Docker Compose

[](#using-docker-compose)

```
services:
  docker-hostfile-sync:
    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest
    container_name: docker-hostfile-sync
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/hosts:/app/hosts
```

```
docker compose up -d
```

Configuration
-------------

[](#configuration)

### Command Line Options

[](#command-line-options)

OptionShortDescriptionDefault`--hosts_file``-f`Path to hosts file`./tmp-hosts``--tld``-t`TLD suffix for hostnames`.docker``--reverse-proxy-host-ip``-r`IP address of your reverse proxy-### Environment Variables

[](#environment-variables)

You can also configure via environment variables:

VariableDescription`HOSTS_FILE`Path to hosts file`TLD`TLD suffix for hostnamesExamples
--------

[](#examples)

### Example 1: Basic Setup

[](#example-1-basic-setup)

A simple web application with a database:

```
# docker-compose.yml
services:
  docker-hostfile-sync:
    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/hosts:/app/hosts

  webapp:
    image: nginx:alpine
    container_name: webapp

  database:
    image: mysql:8
    container_name: database
```

**Generated hosts entries:**

```
## docker-hostsfile-sync
172.20.0.2 webapp.docker webapp.myproject_default
172.20.0.3 database.docker database.myproject_default
## docker-hostsfile-sync-end

```

Now you can access your services:

- `http://webapp.docker` → nginx container
- `mysql -h database.docker` → MySQL container

---

### Example 2: Multiple Networks

[](#example-2-multiple-networks)

When containers are connected to multiple networks, each network gets its own hostname:

```
# docker-compose.yml
services:
  docker-hostfile-sync:
    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/hosts:/app/hosts

  webapp:
    image: nginx:alpine
    container_name: webapp
    networks:
      - frontend
      - backend

  api:
    image: node:alpine
    container_name: api
    networks:
      - backend

  database:
    image: postgres:16
    container_name: database
    networks:
      - backend

networks:
  frontend:
  backend:
```

**Generated hosts entries:**

```
## docker-hostsfile-sync
172.21.0.2 webapp.docker webapp.frontend
172.22.0.2 webapp.backend
172.22.0.3 api.docker api.backend
172.22.0.4 database.docker database.backend
## docker-hostsfile-sync-end

```

This allows:

- Frontend services reach `webapp` via `webapp.frontend`
- Backend services communicate via `*.backend` hostnames
- Your host machine can reach any container directly

---

### Example 3: With Reverse Proxy (nginx-proxy)

[](#example-3-with-reverse-proxy-nginx-proxy)

For production-like setups with a reverse proxy, use the `--reverse-proxy-host-ip` option. This routes URL-like hostnames (containing dots) to your proxy:

```
# docker-compose.yml
services:
  docker-hostfile-sync:
    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/hosts:/app/hosts
    command: --reverse-proxy-host-ip=172.16.238.100

  nginx-proxy:
    image: nginxproxy/nginx-proxy
    container_name: nginx-proxy
    ports:
      - "80:80"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
    networks:
      proxy:
        ipv4_address: 172.16.238.100

  webapp:
    image: nginx:alpine
    container_name: webapp
    environment:
      - VIRTUAL_HOST=webapp.local,www.webapp.local
    networks:
      - proxy
      - default

  api:
    image: node:alpine
    container_name: api
    environment:
      - DOMAIN_NAME=api.local
    networks:
      proxy:
        aliases:
          - api.dev.local
      default:

networks:
  proxy:
    ipam:
      config:
        - subnet: 172.16.238.0/24
```

**Generated hosts entries:**

```
## docker-hostsfile-sync
# nginx-proxy container
172.16.238.100 nginx-proxy.docker nginx-proxy.proxy

# webapp container - direct access via container IP
172.20.0.2 webapp.docker webapp.myproject_default
172.16.238.2 webapp.proxy

# webapp container - reverse proxy routes (from VIRTUAL_HOST env var)
172.16.238.100 webapp.local www.webapp.local

# api container - direct access
172.20.0.3 api.docker api.myproject_default
172.16.238.3 api.proxy

# api container - reverse proxy routes (from DOMAIN_NAME env var and network alias)
172.16.238.100 api.dev.local api.local
## docker-hostsfile-sync-end

```

Now you can:

- Access `http://webapp.local` → routed through nginx-proxy to webapp
- Access `http://api.local` → routed through nginx-proxy to api
- Access `http://webapp.proxy` → direct to webapp container (bypassing proxy)
- Debug with `http://api.docker` → direct container access

---

### Example 4: Network Aliases

[](#example-4-network-aliases)

Network aliases let you give containers additional hostnames. Aliases containing a dot (`.`) are treated as URLs and routed to the reverse proxy:

```
services:
  docker-hostfile-sync:
    image: ghcr.io/webproject-xyz/docker-hosts-file-sync:latest
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/hosts:/app/hosts
    command: --reverse-proxy-host-ip=172.16.238.100

  webapp:
    image: nginx:alpine
    container_name: webapp
    networks:
      default:
        aliases:
          - frontend          # Simple alias → webapp IP
          - app.example.com   # URL-like alias → reverse proxy IP
```

**Generated hosts entries:**

```
## docker-hostsfile-sync
172.20.0.2 webapp.docker frontend.default webapp.default
172.16.238.100 app.example.com
## docker-hostsfile-sync-end

```

How It Works
------------

[](#how-it-works)

The tool manages a section in your hosts file between these markers:

```
## docker-hostsfile-sync
...entries managed automatically...
## docker-hostsfile-sync-end

```

Everything outside these markers is left untouched.

### Hostname Generation Rules

[](#hostname-generation-rules)

SourceExampleGenerated HostnameTarget IPContainer name`webapp``webapp.networkname`Container IPSimple network alias`frontend``frontend.networkname`Container IPURL-like network alias`app.example.com``app.example.com`Reverse proxy IP`DOMAIN_NAME` env var`api.local``api.local`Reverse proxy IP`VIRTUAL_HOST` env var`www.app.local``www.app.local`Reverse proxy IP**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.

Running Locally (Development)
-----------------------------

[](#running-locally-development)

```
# Install dependencies
composer install

# Run (outputs to ./tmp-hosts for testing)
php bin/docker-api synchronize-hosts -v

# Run with reverse proxy support
php bin/docker-api synchronize-hosts -v --reverse-proxy-host-ip=172.16.238.100

# Run targeting /etc/hosts (requires sudo)
sudo php bin/docker-api synchronize-hosts --hosts_file=/etc/hosts -v

# View logs
docker compose logs -f docker-hostfile-sync
```

Troubleshooting
---------------

[](#troubleshooting)

### Hosts file not updating

[](#hosts-file-not-updating)

1. Check the container has write access to the hosts file:

    ```
    docker exec docker-hostfile-sync ls -la /app/hosts
    ```
2. Check logs for errors:

    ```
    docker logs docker-hostfile-sync
    ```

### Container not appearing in hosts file

[](#container-not-appearing-in-hosts-file)

Containers must be "exposed" (have at least one network with an IP address). Check your container:

```
docker inspect  --format '{{json .NetworkSettings.Networks}}'
```

License
-------

[](#license)

MIT

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance72

Regular maintenance activity

Popularity2

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 81.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~19 days

Recently: every ~30 days

Total

25

Last Release

11d ago

PHP version history (3 changes)1.0.0PHP ~8.3.0 || ~8.4.0

1.7.0PHP ~8.3.0 || ~8.4.0 || ~8.5.0

1.8.0PHP ~8.5.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/8126644ebe55d4c9e7d6e496307e6ee2c6232e7af450b1b915de3b282bd44b2d?d=identicon)[Fahl-Design](/maintainers/Fahl-Design)

---

Top Contributors

[![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4)](https://github.com/renovate[bot] "renovate[bot] (364 commits)")[![Fahl-Design](https://avatars.githubusercontent.com/u/6690962?v=4)](https://github.com/Fahl-Design "Fahl-Design (59 commits)")[![semantic-release-bot](https://avatars.githubusercontent.com/u/32174276?v=4)](https://github.com/semantic-release-bot "semantic-release-bot (20 commits)")[![blacksmith-sh[bot]](https://avatars.githubusercontent.com/in/807020?v=4)](https://github.com/blacksmith-sh[bot] "blacksmith-sh[bot] (1 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

clicli-applicationdocker-apidocker-containerhostshostsfilephpphp-docker-apiphp-docker-api-clientsync

###  Code Quality

TestsCodeception

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/webproject-xyz-docker-hostsfile-sync/health.svg)

```
[![Health](https://phpackages.com/badges/webproject-xyz-docker-hostsfile-sync/health.svg)](https://phpackages.com/packages/webproject-xyz-docker-hostsfile-sync)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M3.1k](/packages/craftcms-cms)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M574](/packages/shopware-core)[oro/platform

Business Application Platform (BAP)

645143.5k115](/packages/oro-platform)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[web-auth/webauthn-framework

FIDO2/Webauthn library for PHP and Symfony Bundle.

515100.5k3](/packages/web-auth-webauthn-framework)[2lenet/crudit-bundle

The easy like Crud'it Bundle.

1616.4k14](/packages/2lenet-crudit-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)