papeviso/dresmon repository overview

⁠Dresmon

Keeps /etc/hosts sync with docker state.

Dresmon stands for:

• D - DNS
• RES - resolving
• MON - monitor

⁠Description

Dresmon is a tool designed to keep your /etc/hosts file in sync with the state of your Docker containers. It ensures that as containers start, stop, or change their state, the /etc/hosts file is updated accordingly, allowing for seamless localhost DNS resolution of containerized applications on your host.

⁠Inspiration

This project was inspired by discussions in the developer community about the need for a tool that bridges the gap between Docker's dynamic nature and the static nature of the /etc/hosts file. Further inspiration was drawn from projects like JWilder Nginx-Proxy and Traefik.

For a detailed list of inspirations, please refer to CREDITS.md.

⁠Prerequisites

⁠On Host

• Docker installed and running.
• Python 3.x
• Appropriate permissions to modify the /etc/hosts file.

⁠In a Docker Container

• Docker daemon accessible (usually via Docker-in-Docker or mounting the Docker socket).
• Python 3.x (included into a prebuilt image and also added as a dependency to install in Dockerfile)

⁠Usage

⁠Usage on Host

1. Clone the repository:

   git clone https://github.com/PapevisO/dresmon.git
   

   Copy

2. Navigate to the project directory:

   cd dresmon
   

   Copy

3. Build and Run

   1. Using Docker Compose with pre-built image:

      • Update the docker-compose.yml to use the image from Docker Hub:

      services:
        dresmon:
          image: papeviso/dresmon:latest
          volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
            - /etc/hosts:/etc/hosts
      

      Copy
      • Run using Docker Compose:

      docker-compose up -d dresmon
      

      Copy

      or if it's the only service in your project

      docker-compose up -d
      

      Copy

   2. Using Docker Compose with manual separately from the project build:

      • Build the image:

      docker build -t dresmon .
      

      Copy
      • Update the docker-compose.yml to use the locally built image:

      services:
        dresmon:
          image: dresmon
          volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
            - /etc/hosts:/etc/hosts
      

      Copy
      • Run using Docker Compose:

      docker-compose up -d dresmon
      

      Copy

   3. Using Docker Compose with Compose managed build:

      • Clone Dresmon repository to project subdirectory:

      git clone https://github.com/PapevisO/dresmon.git
      

      Copy
      • Update the docker-compose.yml to use the locally built image:

      services:
        dresmon:
          build: dresmon
          volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
            - /etc/hosts:/etc/hosts
      

      Copy
      • Build the image:

      docker-compose up -d --build dresmon
      

      Copy

4. Monitor the logs to ensure Dresmon is functioning as expected:

docker-compose logs -f

⁠Usage with Docker

1. Pull the Dresmon image:

   docker pull papeviso/dresmon
   

   Copy

2. Run the Dresmon container, ensuring the Docker daemon is accessible:

   docker run \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v /etc/hosts:/etc/hosts \
       papeviso/dresmon
   

   Copy

3. Alternatively, you can build the image inside another Docker container and run it similarly.

⁠Environment Variables

• DRESMON_EXCLUDE: Domains to exclude from being added to /etc/hosts. Supports wildcard patterns. Delimitered by comma.
• DRESMON_TLD: Top-level domains that Dresmon should manage. Delimitered by comma. Useful for filtering out unwanted domains.

⁠Links

1. GitHub Repository https://github.com/PapevisO/dresmon⁠

2. Docker Hub https://hub.docker.com/r/papeviso/dresmon⁠

⁠State transition diagram

Diagram source on Mermaid⁠