https://github.com/foxscore/docker-hosts
https://github.com/foxscore/docker-hosts
Last synced: 23 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/foxscore/docker-hosts
- Owner: foxscore
- Created: 2026-02-08T17:33:19.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-08T17:33:21.000Z (5 months ago)
- Last Synced: 2026-05-16T16:21:36.425Z (2 months ago)
- Language: Python
- Size: 3.91 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# docker-hosts-manager
> [!NOTE]
> This tool was created entirely with the assistance of GitHub Copilot.
> [!TIP]
> Make a backup of your hosts file before running. Example:
>
> ```sh
> cp /etc/hosts /etc/hosts.bak
> ```
> [!WARNING]
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
`docker-hosts-manager` watches the Docker socket and keeps a managed block in the host's `/etc/hosts` file mapping container names to their container IPs. This allows you to access containers from the host by name (for example `http://example:5001`) without publishing ports.
# Quick local build & run
```bash
# build locally (tagged for GHCR)
docker build -t ghcr.io/foxscore/docker-hosts:latest .
# run manager (must mount docker socket and make /etc/hosts writable)
docker run -d \
--name docker-hosts-manager \
--restart unless-stopped \
-e RECONCILE_INTERVAL=10 \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /etc/hosts:/etc/hosts:rw \
ghcr.io/foxscore/docker-hosts:latest
```
Files and behavior
- The manager keeps a managed block in the hosts file delimited by these markers:
- `# BEGIN DOCKER-HOSTS-MANAGER`
- `# END DOCKER-HOSTS-MANAGER`
- It lists entries of the form `IPcontainer-name` for each running container that has a container network IP.
- The default polling interval is controlled by the `RECONCILE_INTERVAL` env var (seconds).
- The hosts file path can be overridden with `HOSTS_FILE` if needed (default `/etc/hosts`).
Security & safety notes
- This service requires privileged access: a mounted Docker socket and write access to `/etc/hosts`. Both are powerful privileges — treat them carefully.
- The manager uses a marker block to avoid clobbering unrelated entries, but it's still possible for concurrent editors or misconfiguration to corrupt `hosts`. Backups and strict permissions are recommended.
- To reduce risk, run the manager only on trusted hosts, and restrict container runtime access.
Publishing to GHCR
This repository includes a GitHub Actions workflow to build and publish the image to GitHub Container Registry (GHCR) using the image tag `ghcr.io/foxscore/docker-hosts:latest`.
Local helper
- `build.sh` (included) builds the image locally and tags it as `ghcr.io/foxscore/docker-hosts:latest`.
GitHub Actions notes
- The workflow `/.github/workflows/publish.yml` triggers on `push` to `main` and `workflow_dispatch`.
- It uses the automatically-provided `GITHUB_TOKEN` for login and pushes the image to GHCR. No additional secrets are required for the default setup, but you can use a personal access token if needed for cross-repository publishing.
Further improvements
- Atomic write + backups of `/etc/hosts`.
- Support for aliases, IPv6 addresses, and network filters.
- More robust locking (flock) and verification to protect against symlink attacks.
If you want, I can add atomic writes and automatic backups to the manager implementation.