Dynamic service Discovery

dynamic service discovery, container syncing, automatic updates

⚡ Real-time · 🔄 Automatic · 🚀 Easy to Deploy

Installation

Important

ServDiscovery works only with Traefik. It will not work with other reverse proxies due to using traefik labels to determine routes.

Get the latest docker-compose.yaml:

services:
discovery:
image: ghcr.io/codeshelldev/servdiscovery:latestcontainer_name: service-discoveryenvironment:
ENDPOINT: https://mydomain.com/discoverENDPOINT_KEY: MY_VERY_SECURE_KEYDISCOVERY_INTERVAL: 60ALIVE_INTERVAL: 60SERVER_NAME: server-1volumes:
- /var/run/docker.sock:/var/run/docker.sock

Then spin it up:

docker compose up -d

Your discovery service is now live! 🎉

Usage

Let's take a simple whoami container as an example:

services:
whoami:
image: traefik/whoami:latestcontainer_name: whoamilabels:
- traefik.enable=true
- traefik.http.routers.whoami.rule=Host(`whoami.mydomain.com`)
- traefik.http.routers.whoami.entrypoints=websecure
- traefik.http.routers.whoami.tls=true
- traefik.http.routers.whoami.tls.certresolver=cloudflare
- traefik.http.routers.whoami.service=whoami-svc
- traefik.http.services.whoami-svc.loadbalancer.server.port=80# Enable Discovery for this Container
- discovery.enable=truenetworks:
- traefiknetworks:
traefik:
external: true

Whenever a new Host-Rule is added or updated, ServDiscovery will automatically notify the configured endpoint.
This ensures the endpoint can correctly route traffic based on SNI / Hostnames.

Endpoint Integration

ServDiscovery communicates with your endpoint via JSON HTTP Requests:

{
"serverName": "server-1",
"diff": {
"added": [
"whoami.mydomain.com",
"website.mydomain.com",
"auth.mydomain.com"
],
"removed": [
"whoami-backup.mydomain.com",
"website-backup.mydomain.com",
"auth-backup.mydomain.com"
]
}
}

Example explanation:

✅ Available	❌ Unavailable
whoami.mydomain.com	whoami-backup.mydomain.com
website.mydomain.com	website-backup.mydomain.com
auth.mydomain.com	auth-backup.mydomain.com

This allows the endpoint (e.g., a load balancer) to remove \*-backup records from your registry and update routable containers/services automatically.

Integrations

You can find example integrations inside of examples/.

Configuration

ENDPOINT_KEY

The endpoint key is used in the Authorization header (Bearer token) when ServDiscovery sends POST requests.
If no key is provided, the header is omitted.

DISCOVERY_INTERVAL

Time (in seconds) between updates to your endpoint.
Default:60 seconds

ALIVE_INTERVAL

Time (in seconds) between full alive discoveries. ServDiscovery sends a complete update of all active containers in the added JSON key.
Default:120 seconds

Contributing

Found a bug or have a brilliant idea? Contributions are welcome! Open an issue or create a pull request — your help makes this project better.

License

This project is licensed under the MIT License.