{"id":17132199,"url":"https://github.com/bitsofinfo/docker-discovery-registrator-consul","last_synced_at":"2025-04-13T07:56:03.547Z","repository":{"id":57738965,"uuid":"54587511","full_name":"bitsofinfo/docker-discovery-registrator-consul","owner":"bitsofinfo","description":"Service discovery library for JVM based applications running in Docker containers that use the Registrator service registry bridge with Consul as a backend","archived":false,"fork":false,"pushed_at":"2021-02-09T19:21:36.000Z","size":596,"stargazers_count":22,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-13T07:55:58.527Z","etag":null,"topics":["consul","discovery","docker","docker-container","jvm","registrator"],"latest_commit_sha":null,"homepage":"https://bitsofinfo.wordpress.com/2016/06/02/docker-discover-ip-port-java/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitsofinfo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-23T19:30:56.000Z","updated_at":"2024-01-13T23:55:05.000Z","dependencies_parsed_at":"2022-08-24T17:40:16.315Z","dependency_job_id":null,"html_url":"https://github.com/bitsofinfo/docker-discovery-registrator-consul","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-registrator-consul","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-registrator-consul/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-registrator-consul/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-registrator-consul/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsofinfo","download_url":"https://codeload.github.com/bitsofinfo/docker-discovery-registrator-consul/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681490,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["consul","discovery","docker","docker-container","jvm","registrator"],"created_at":"2024-10-14T19:26:21.216Z","updated_at":"2025-04-13T07:56:03.509Z","avatar_url":"https://github.com/bitsofinfo.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docker-discovery-registrator-consul\n\nService discovery library for JVM based applications running in Docker containers that use the [Registrator](https://github.com/gliderlabs/registrator) service registry bridge with [Consul](https://consul.io/) as a backend. \n\nThe purpose of this library is for \"self-discovery\" from within your JVM based Docker application where you need to discover what\nyour accessible docker-host bound IP and mapped port(s) are, as well as your peers within the same service. This is critical if your container has to do further peer discovery\nfor other services it provides or clustering groups it must form.\n\n* [Status](#status)\n* [Releases](#releases)\n* [Requirements](#requirements)\n* [Maven/Gradle install](#mavengradle)\n* [Features](#features)\n* [Usage Overview](#usageoverview)\n* [Running example](#runningexample)\n* [Build from source](#building)\n* [Unit tests](#tests)\n* [Logging](#logging)\n* [Related Info](#related)\n* [Todo](#todo)\n* [Notes](#notes)\n* [Docker info](#docker)\n\n![Diagram of docker discovery consul registrator](/docs/diag1.png \"Diagram1\")\n\n## \u003ca id=\"status\"\u003e\u003c/a\u003eStatus\n\nBeta code. Master branch available only.\n\n**IMPORTANT:**: Do not rely on JCenter/Bintray anymore! Update your gradle/maven dependencies to use Maven Central: https://search.maven.org/search?q=g:org.bitsofinfo\n\n## \u003ca id=\"releases\"\u003e\u003c/a\u003eReleases\n\n* MASTER - in progress, this README refers to what is in the master branch. Switch to relevant RELEASE tag above to see that versions README\n\n* [1.0-RC4-20210205](https://github.com/bitsofinfo/docker-discovery-registrator-consul/releases/tag/1.0-RC4-20210205) - same as 1.0-RC4 but made compliant for Maven Central due to JCenter/Bintray closure.\n* [1.0-RC4](https://github.com/bitsofinfo/docker-discovery-registrator-consul/releases/tag/1.0-RC4) - upgraded consul-client to 0.17.1\n* [1.0-RC3](https://github.com/bitsofinfo/docker-discovery-registrator-consul/releases/tag/1.0-RC3)\n* [1.0-RC2](https://github.com/bitsofinfo/docker-discovery-registrator-consul/releases/tag/1.0-RC2)\n* [1.0-RC1](https://github.com/bitsofinfo/docker-discovery-registrator-consul/releases/tag/1.0-RC1)\n\n## \u003ca id=\"requirements\"\u003e\u003c/a\u003eRequirements\n\n* Java 6+\n* Your application is running in a Docker container, using this library for discovery\n* Your Docker host has a [Registrator](https://github.com/gliderlabs/registrator) container running prior to launch of your app\n* The Registrator container is configured to use [Consul](https://consul.io/) as its registry backend\n\n## \u003ca id=\"mavengradle\"\u003e\u003c/a\u003eMaven/Gradle\n\nTo use this discovery strategy in your Maven or Gradle project use the dependency samples below. (coming soon)\n\n### Gradle:\n\n```\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    compile 'org.bitsofinfo:docker-discovery-registrator-consul:1.0-RC4-20210205'\n\n    // include your preferred javax.ws.rs-api implementation\n    // (for the OrbitzWorldwide/consul-client dependency)\n    // for example below:\n    compile 'javax.ws.rs:javax.ws.rs-api:2.0.1'\n    compile 'org.glassfish.jersey.core:jersey-client:2.22.2'\n    compile 'org.slf4j:slf4j-api:1.7.19'\n}\n```\n\n### Maven:\n\n```\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.bitsofinfo\u003c/groupId\u003e\n        \u003cartifactId\u003edocker-discovery-registrator-consul\u003c/artifactId\u003e\n        \u003cversion\u003e1.0-RC4-20210205\u003c/version\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- include your preferred javax.ws.rs-api\n         (for the https://github.com/OrbitzWorldwide/consul-client dependency)\n         implementation - see gradle example above\n    --\u003e\n\u003c/dependencies\u003e\n```\n\n## \u003ca id=\"features\"\u003e\u003c/a\u003eFeatures\n\n* Permits a JVM based container application to self-discover all of its mapped ports and accessible ip address, as well of that as all of its peer \"services\" that share the same service name, ports and/or service tags, as set by Registrator in Consul.\n\n\n## \u003ca id=\"usageoverview\"\u003e\u003c/a\u003eUsage overview\n\nIts **highly recommended** that you walking the example below in the section below. Overall the concept and API is quite simple.\n\n1. You launch your container that utilizes this library, passing both Registrator (via `-e` args) and your container the required arguments (or via other configuration means) about how to connect to Consul, its unique identifier, serviceName, and any \"tags\" it might need to know about related to discovery.\n\n2. In your app's code, you create a new [ConsulDiscovery](src/main/java/org/bitsofinfo/docker/discovery/registrator/consul/ConsulDiscovery.java)\ninstance, giving it the required constructor args or properties via the builder syntax for how to connect to Consul, its unique ID, serviceName,\ntags etc.\n\n3. Once constructed you can call the various methods on [ConsulDiscovery](src/main/java/org/bitsofinfo/docker/discovery/registrator/consul/ConsulDiscovery.java) such as `discoverPeers()`, `discoverMe()`, `discoverPeers(portFilter)`, `discoverMe(portFilter)`, which returns a \ncollection of [ServiceInfo](src/main/java/org/bitsofinfo/docker/discovery/registrator/consul/ServiceInfo.java) instances, each representing\na specific `ip:port` binding for the participating node that shares the `service-name` as Registrator placed in Consul.\n\n4. There are two different strategies that can be used when setting up your [ConsulDiscovery](src/main/java/org/bitsofinfo/docker/discovery/registrator/consul/ConsulDiscovery.java) instance. They are as follows, (see javadoc in source for more details):\n\n  * [MultiServiceNameSinglePortStrategy](src/main/java/org/bitsofinfo/docker/discovery/registrator/consul/MultiServiceNameSinglePortStrategy.java) - See source code javadoc for details. Used when you specify a Registrator consumed environment variable `-e SERVICE_[port]_NAME` or completely omit it entirely (i.e. you don't pass any `-e SERVICE_[port]_NAME=xxx`). The result is a unique `\u003cserviceName\u003e-\u003cport\u003e` service registered in the Consul catalog by Registrator for each unique port exposed by your container. All nodes exposing a port are listed under the same `\u003cserviceName\u003e-\u003cport\u003e` in the Consul service catalog. See [Registrator doc](http://gliderlabs.com/registrator/latest/user/services/#service-name) \n  \n  * [OneServiceNameMultiPortStrategy](src/main/java/org/bitsofinfo/docker/discovery/registrator/consul/OneServiceNameMultiPortStrategy.java) - See source code javadoc for details. Used when you specify a `-e SERVICE_NAME=xxx` shared service name syntax (note, there is NO port info in service name). The result is you end up with one service name in Consul yielding many unique `node:port` listings, one for every port exposed by a node sharing that service name. (i.e. if you have 2 ports per node, and 2 containers, the service listing yields 4 listings) See [Registrator doc](http://gliderlabs.com/registrator/latest/user/services/#service-name)\n  \n#### Sample code:\n\n```\nConsulDiscovery c = new ConsulDiscovery()\n                        .setConsulUrl(new URL(\"http://192.168.0.200:8500\"))\n                        \n                        // \"service name\" base in Consul that Registrator\n                        // will list this container-app under. Either just \n                        // \"serviceName\" or \"serviceName-port\" depending on\n                        // what -e variable approach you took when launching\n                        // the container see: http://gliderlabs.com/registrator/latest/user/services/#service-name\n                        .setServiceName(\"my-app-name\") \n                        \n                        // optional acl token\n                        // .setConsulAclToken(\"some-token\")\n                        \n                         // both Registrator (via -e SERVICE_TAGS=[..,thisUniqueId001]) AND your app need this! \n                        .setMyNodeUniqueTagId(\"thisUniqueId001\") \n                        \n                        // what ports you care about discovering info about\n                        .addPortToDiscover(8080)\n                        .addPortToDiscover(8443)\n                        \n                         // optional, additional tag to filter on\n                         // again Registrator  needs this too via (via -e SERVICE_TAGS=[staging,tag2,thisUniqueId001]) \n                        .addMustHaveTag(\"staging\")\n                        \n                        // the service name strategy to use, expained above, see JavaDoc in \n                        // ServiceNameStrategy implementations for specifics\n                        .setServiceNameStrategyClass(MultiServiceNameSinglePortStrategy.class);\n                        \n// the port is optional, see Javadoc\n// yields a list of all ServiceInfo's for all nodes\n// other than THIS node, which have that port mapped.\nCollection\u003cServiceInfo\u003e allServiceNodes = c.discoverPeers(8443);\n\n```\n\n## \u003ca id=\"logging\"\u003e\u003c/a\u003e Logging\n\nThis library uses slf4j. If you enable TRACE logging for `org.bitsofinfo.docker.discovery.registrator.consul` additional verbose\ndebugging information will appear\n\n\n## \u003ca id=\"runningexample\"\u003e\u003c/a\u003eRunning example\n\n* The simplist way to see how to use this library is first, review the code in [SampleContainerApp.java](src/main/java/org/bitsofinfo/docker/discovery/registrator/consul/sample/SampleContainerApp.java). The API is quite simple and fairly straight forward.\n\n* Have Consul running and available somewhere on your network, start it such as: (adjust paths below)\n    ```\n    consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul -config-dir /path/to/consul.d/ -ui-dir /path/to/consul-web-ui -bind=0.0.0.0 -client=0.0.0.0\n    ```\n\n* On your Docker host ensure Registrator is running such as: \n    ```\n    docker run -d --name=registrator --net=host --volume=/var/run/docker.sock:/tmp/docker.sock  gliderlabs/registrator:latest consul://[YOUR_CONSUL_IP]:8500\n    ```\n\n* In the root of the project:\n\n    ```\n    cd sample/\n    ./build-image.sh\n    ```\n\n    ```\n    docker images\n\n    REPOSITORY                                    TAG                     IMAGE ID            CREATED             VIRTUAL SIZE\n    docker-discovery-registrator-consul-sample    latest                  750dc9aa5052        18 minutes ago      651.5 MB\n    ```\n\n* Now run the sample image you built 3x, (you can do more if you want). NOTE! Be sure to adjust the `-DMY_UNIQUE_TAG=`, `-DCONSUL_URL=http(s)://[YOUR_CONSUL_IP]:8500`, and ` -e \"SERVICE_TAGS=dev,myUniqueId003\"` properties below in each command for each instance launched to give it a unique id, and correct consul ip.\n\n\t```\n\tdocker run -e \"SERVICE_TAGS=dev,myUniqueId001\" --rm=true -P docker-discovery-registrator-consul-sample:latest java -DMY_SERVICE_NAME=docker-discovery-registrator-consul-sample -DMY_UNIQUE_TAG=myUniqueId001 -DCONSUL_URL=http(s)://[YOUR_CONSUL_IP]:8500 -DSERVICE_NAME_STRATEGY=org.bitsofinfo.docker.discovery.registrator.consul.MultiServiceNameSinglePortStrategy -jar /sample/sample.jar\n\t\n\tdocker run -e \"SERVICE_TAGS=dev,myUniqueId002\" --rm=true -P docker-discovery-registrator-consul-sample:latest java -DMY_SERVICE_NAME=docker-discovery-registrator-consul-sample -DMY_UNIQUE_TAG=myUniqueId002 -DCONSUL_URL=http(s)://[YOUR_CONSUL_IP]:8500 -DSERVICE_NAME_STRATEGY=org.bitsofinfo.docker.discovery.registrator.consul.MultiServiceNameSinglePortStrategy -jar /sample/sample.jar\n\t\n\tdocker run -e \"SERVICE_TAGS=dev,myUniqueId003\" --rm=true -P docker-discovery-registrator-consul-sample:latest java -DMY_SERVICE_NAME=docker-discovery-registrator-consul-sample -DMY_UNIQUE_TAG=myUniqueId003 -DCONSUL_URL=http(s)://[YOUR_CONSUL_IP]:8500 -DSERVICE_NAME_STRATEGY=org.bitsofinfo.docker.discovery.registrator.consul.MultiServiceNameSinglePortStrategy -jar /sample/sample.jar\n\t```\n\n* Every 10 seconds, each instance of the sample container app, will report the discovery information about itself and its peers:\n\n\n\tFrom container one's perspective:\n\t```\n\t########## myUniqueId001 REPORTING: ##########\n\tMY SERVICES:\n\t/192.168.99.100:32846 -\u003e container:8080 tags: [dev, myUniqueId001]\n\t/192.168.99.100:32845 -\u003e container:8443 tags: [dev, myUniqueId001]\n\t\n\t\n\tMY PEER SERVICES:\n\t/192.168.99.100:32842 -\u003e container:8080 tags: [dev, myUniqueId003]\n\t/192.168.99.100:32844 -\u003e container:8080 tags: [dev, myUniqueId002]\n\t/192.168.99.100:32841 -\u003e container:8443 tags: [dev, myUniqueId003]\n\t/192.168.99.100:32843 -\u003e container:8443 tags: [dev, myUniqueId002]\n\t########## END myUniqueId001 ############\n\t```\n\t\n\tFrom container two's perspective:\n\t```\n\t########## myUniqueId002 REPORTING: ##########\n\tMY SERVICES:\n\t/192.168.99.100:32844 -\u003e container:8080 tags: [dev, myUniqueId002]\n\t/192.168.99.100:32843 -\u003e container:8443 tags: [dev, myUniqueId002]\n\t\n\t\n\tMY PEER SERVICES:\n\t/192.168.99.100:32842 -\u003e container:8080 tags: [dev, myUniqueId003]\n\t/192.168.99.100:32846 -\u003e container:8080 tags: [dev, myUniqueId001]\n\t/192.168.99.100:32841 -\u003e container:8443 tags: [dev, myUniqueId003]\n\t/192.168.99.100:32845 -\u003e container:8443 tags: [dev, myUniqueId001]\n\t########## END myUniqueId002 ############\n\t```\n\t\n\tFrom container three's perspective:\n\t```\n\t########## myUniqueId003 REPORTING: ##########\n\tMY SERVICES:\n\t/192.168.99.100:32842 -\u003e container:8080 tags: [dev, myUniqueId003]\n\t/192.168.99.100:32841 -\u003e container:8443 tags: [dev, myUniqueId003]\n\t\n\t\n\tMY PEER SERVICES:\n\t/192.168.99.100:32844 -\u003e container:8080 tags: [dev, myUniqueId002]\n\t/192.168.99.100:32846 -\u003e container:8080 tags: [dev, myUniqueId001]\n\t/192.168.99.100:32843 -\u003e container:8443 tags: [dev, myUniqueId002]\n\t/192.168.99.100:32845 -\u003e container:8443 tags: [dev, myUniqueId001]\n\t########## END myUniqueId003 ############\n\t```\n\n## \u003ca id=\"building\"\u003e\u003c/a\u003eBuilding from source\n\n* From the root of this project, build a Jar : `./gradlew assemble`\n\n* Include the built jar artifact located at `build/libs/docker-discovery-registrator-consul-[VERSION].jar` in your JVM based project\n\n* If not already present in your hazelcast application's Maven (pom.xml) or Gradle (build.gradle) dependencies section; ensure that these dependencies are present (versions may vary as appropriate):\n\t\n\t```\n\tcompile group: 'com.orbitz.consul', name: 'consul-client', version:'0.17.1'\n\tcompile 'javax.ws.rs:javax.ws.rs-api:2.0.1'\n\tcompile 'org.glassfish.jersey.core:jersey-client:2.22.2'\n\tcompile 'org.slf4j:slf4j-api:1.7.19'\n\t```\n\n\n## \u003ca id=\"tests\"\u003e\u003c/a\u003eUnit-tests\n\nComing soon\n\n## \u003ca id=\"related\"\u003e\u003c/a\u003eRelated info\n\n* https://www.consul.io\n* https://github.com/gliderlabs/registrator\n* https://github.com/docker/docker/issues/3778\n\n## \u003ca id=\"todo\"\u003e\u003c/a\u003eTodo\n\n* Coming soon\n\n## \u003ca id=\"notes\"\u003e\u003c/a\u003e Notes\n\n* Coming soon\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fdocker-discovery-registrator-consul","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsofinfo%2Fdocker-discovery-registrator-consul","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fdocker-discovery-registrator-consul/lists"}