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

2. Navigate to the project directory:

   cd dresmon

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

      • Run using Docker Compose:

      docker-compose up -d dresmon

      or if it's the only service in your project

      docker-compose up -d

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

      • Build the image:

      docker build -t dresmon .

      • 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

      • Run using Docker Compose:

      docker-compose up -d dresmon

   3. Using Docker Compose with Compose managed build:

      • Clone Dresmon repository to project subdirectory:

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

      • 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

      • Build the image:

      docker-compose up -d --build dresmon

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

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

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