https://github.com/deepspace2/plugnpin
Automatically scrapes containers with specific labels and creates local DNS entries in Pi-Hole and proxy hosts in Nginx Proxy Manager
https://github.com/deepspace2/plugnpin
container docker labels nginx-proxy-manager npm pi-hole
Last synced: about 2 months ago
JSON representation
Automatically scrapes containers with specific labels and creates local DNS entries in Pi-Hole and proxy hosts in Nginx Proxy Manager
- Host: GitHub
- URL: https://github.com/deepspace2/plugnpin
- Owner: DeepSpace2
- Created: 2025-08-15T19:29:29.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-08-16T10:02:15.000Z (10 months ago)
- Last Synced: 2025-08-16T10:14:11.824Z (10 months ago)
- Topics: container, docker, labels, nginx-proxy-manager, npm, pi-hole
- Language: Go
- Homepage: https://deepspace2.github.io/PlugNPiN/
- Size: 584 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://goreportcard.com/report/github.com/DeepSpace2/PlugNPiN)
[](https://github.com/DeepSpace2/PlugNPiN/releases)
# 🔌 PlugNPiN
**Plug and play your docker containers into Pi-Hole/AdGuard Home & Nginx Proxy Manager**
Automatically detect running Docker containers based on labels, add them
as local DNS/CNAME records in **Pi-Hole** (or DNS Rewrites in **AdGuard Home**) and create matching proxy hosts in
**Nginx Proxy Manager**.
## Key Features
- Automatic Docker container detection (monitoring multiple hosts is supported)
- Local DNS/CNAME record creation/deletion in Pi-hole
- DNS Rewrites creation/deletion in AdGuard Home
- Nginx Proxy Manager host creation
- Support for Docker socket proxy
**Pi-Hole's and AdGuard Home's functionality can be toggled individually. By default Pi-Hole is enabled and AdGuard Home is disabled.**
**[See the documentation site for full setup and configuration.](https://deepspace2.github.io/PlugNPiN)**
## How it Works
PlugNPiN discovers services by scanning for Docker containers that have the following labels:
- `plugNPiN.ip` - The IP address and port of the container (e.g., `192.168.1.100:8080`).
- `plugNPiN.url` - The desired URL for the service (e.g., `my-service.local`).
The application operates in two complementary modes to keep your services synchronized:
1. **Real-Time Event Listening**: The application actively listens for Docker container events. When a container with the required labels is **started**, **stopped**, or **killed**, the tool immediately adds or removes the corresponding DNS and proxy host entries. This ensures that your services are updated in real-time as containers change state.
2. **Periodic Synchronization**: In addition to real-time events, the tool performs a full synchronization at a regular interval, defined by the `RUN_INTERVAL` environment variable. During this periodic run, it scans all running containers and ensures that their DNS and proxy configurations are correct. This acts as a self-healing mechanism, correcting any entries that might have been missed or become inconsistent.
When a container is processed in either mode, PlugNPiN will:
1. Create a DNS record pointing the specified `url` to the `ip` address on **Pi-Hole/AdGuard Home** (or a CNAME record pointing to a configurable target domain).
2. Create a proxy host to route traffic from the `url` to the container's `ip` and `port` on **Nginx Proxy Manager**.
## Usage
### Docker Compose
It is **highly recommended** to use a Docker socket proxy to avoid giving the container direct access to the Docker daemon. This improves security by limiting the container's privileges.
#### Recommended: Using a Docker Socket Proxy
```yaml
services:
socket-proxy:
image: lscr.io/linuxserver/socket-proxy:latest
container_name: socket-proxy
environment:
# Allow access to the container list
- CONTAINERS=1
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
read_only: true
tmpfs:
- /run
plugnpin:
image: ghcr.io/deepspace2/plugnpin:latest
container_name: plugnpin
depends_on:
- socket-proxy
environment:
- DOCKER_HOST=tcp://socket-proxy:2375
- NGINX_PROXY_MANAGER_HOST=...
- NGINX_PROXY_MANAGER_USERNAME=...
- NGINX_PROXY_MANAGER_PASSWORD=...
- PIHOLE_HOST=...
- PIHOLE_PASSWORD=...
restart: unless-stopped
```
#### Not Recommended: Directly mounting the Docker Socket
```yaml
services:
plugnpin:
image: ghcr.io/deepspace2/plugnpin:latest
container_name: plugnpin
environment:
- NGINX_PROXY_MANAGER_HOST=...
- NGINX_PROXY_MANAGER_USERNAME=...
- NGINX_PROXY_MANAGER_PASSWORD=...
- PIHOLE_HOST=...
- PIHOLE_PASSWORD=...
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stopped
```
## Contributing
Contributions are very welcome! If you have a feature request, bug report, or want to contribute yourself, please feel free to open an issue or submit a pull request.