{"id":15919948,"url":"https://github.com/bitsofinfo/docker-discovery-swarm-service","last_synced_at":"2025-04-03T12:14:19.466Z","repository":{"id":57738967,"uuid":"96434087","full_name":"bitsofinfo/docker-discovery-swarm-service","owner":"bitsofinfo","description":"Service discovery library for JVM based applications running in Docker containers deployed as Swarm Services","archived":false,"fork":false,"pushed_at":"2021-02-09T19:20:41.000Z","size":272,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-09T01:33:01.402Z","etag":null,"topics":["container","discovery","docker","java","jvm","swarm"],"latest_commit_sha":null,"homepage":"https://bitsofinfo.wordpress.com/2017/10/09/docker-container-peer-ip-discovery-with-swarm-services/","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":"2017-07-06T13:36:34.000Z","updated_at":"2021-02-09T19:20:44.000Z","dependencies_parsed_at":"2022-08-24T17:40:18.822Z","dependency_job_id":null,"html_url":"https://github.com/bitsofinfo/docker-discovery-swarm-service","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-swarm-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-swarm-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-swarm-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitsofinfo%2Fdocker-discovery-swarm-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitsofinfo","download_url":"https://codeload.github.com/bitsofinfo/docker-discovery-swarm-service/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246998218,"owners_count":20866696,"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":["container","discovery","docker","java","jvm","swarm"],"created_at":"2024-10-06T19:07:19.672Z","updated_at":"2025-04-03T12:14:19.449Z","avatar_url":"https://github.com/bitsofinfo.png","language":"Java","readme":"# docker-discovery-swarm-service\n\nPeer discovery library for JVM based applications running in Docker containers deployed as Swarm Services\n\n[![Build Status](https://travis-ci.org/bitsofinfo/docker-discovery-swarm-service.svg?branch=master)](https://travis-ci.org/bitsofinfo/docker-discovery-swarm-service)\n\nThe purpose of this library is for \"self-discovery\" from within your JVM based Docker swarm service application where you need to discover what your overlay IP is, as well as your peers within the same service. This is critical if your container has to do further peer discovery for 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\n\n![Diagram of docker discovery swarm service](/docs/diag1.png \"Diagram1\")\n\n## \u003ca id=\"status\"\u003e\u003c/a\u003eStatus\n\nBeta code. \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-RC5-20210205](https://github.com/bitsofinfo/docker-discovery-registrator-consul/releases/tag/1.0-RC5-20210205) - same as 1.0-RC5 but made compliant for Maven Central due to JCenter/Bintray closure. Spotify docker-client set explicitly to 8.15.0\n\n* [1.0-RC5](https://github.com/bitsofinfo/docker-discovery-swarm-service/releases/tag/1.0-RC) - Better NPE handling for invalid/null Tasks returned from service spec or no network attachments\n\n* [1.0-RC4](https://github.com/bitsofinfo/docker-discovery-swarm-service/releases/tag/1.0-RC4) - support for skip verify TLS to Swarm Managers\n\n* [1.0-RC3](https://github.com/bitsofinfo/docker-discovery-swarm-service/releases/tag/1.0-RC3) - upgrade spotify docker-client\n\n* [1.0-RC2](https://github.com/bitsofinfo/docker-discovery-swarm-service/releases/tag/1.0-RC2) - excludes stopped tasks\n\n* [1.0-RC1](https://github.com/bitsofinfo/docker-discovery-swarm-service/releases/tag/1.0-RC1)\n\n## \u003ca id=\"requirements\"\u003e\u003c/a\u003eRequirements\n\n* Java 7+\n* [Docker 1.12+ Swarm Mode](https://docs.docker.com/engine/swarm/) with one or more swarm manager nodes listening on a `tcp://`, `http://` or `https://` socket\n* Your application is running in a Docker container and deployed as a swarm service, using this library for discovery\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-swarm-service:1.0-RC5-20210205'\n}\n```\n\n### Maven:\n\n```\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.bitsofinfo\u003c/groupId\u003e\n        \u003cartifactId\u003edocker-discovery-swarm-service\u003c/artifactId\u003e\n        \u003cversion\u003e1.0-RC5-20210205\u003c/version\u003e\n    \u003c/dependency\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 its ip address on a docker overlay network, as well as those of all of its peer containers as identified by matching Docker network names, service names and/or service labels.\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 as a Docker Swarm Service on a Docker Overlay Network, specifying a `DOCKER_HOST`  (via `-e` args) that points to a Swarm Manager listening on `tcp://`, `http://` or `https://` and your container the required arguments (or via other configuration means) about the relevant `dockerNetworkNames`, `dockerServiceNames`, and any `dockerServiceLabels` it will use to locate itself and peer containers in the swarm service via the `/networks`, `/services` and `/tasks` APIs provided by the configured `DOCKER_HOST` (which should point to one or more swarm managers, i.e. via dns etc. `http(s)://swarmmgrs:237[5|6]`)\n\n2. In your app's code, you create a new [SwarmServiceDiscovery](src/main/java/org/bitsofinfo/docker/discovery/swarm/service/SwarmServiceDiscovery.java) instance, giving it the required constructor args or properties via the builder syntax for the docker network, service names and labels to utilize.\n\n3. Once constructed you can call the various methods on [SwarmServiceDiscovery](src/main/java/org/bitsofinfo/docker/discovery/swarm/service/SwarmServiceDiscovery.java) such as `getMyIpAddress()`, `getMyContainer()`, or `discoverContainers()`, which are backed by [DiscoveredContainer](src/main/java/org/bitsofinfo/docker/discovery/swarm/service/DiscoveredContainer.java) instances, each containing various methods about each container i.e. `getIp()`.\n\n  \n#### Sample code:\n\n```\n\n/**\n\n  PRIOR TO RUNNING THIS CODE:\n  \n  You must have the following environment variable set:\n \n  DOCKER_HOST=http://[swarmmgr]:[port]\n  \n**/\n\n// Reliant on value within DOCKER_HOST env var\nSwarmServiceDiscovery ssd = new SwarmServiceDiscovery()\n                            .addDockerNetworkName(\"my-service-net\")\n                            .addDockerServiceName(\"my-service-01\")\n                            \n                            // optional label filter\n                            .addDockerServiceLabel(\"production\");\n                        \n// get my ip on the docker overlay network\nInetAddress myIp = ssd.getMyIpAddress();\n                        \n// gets all nodes inclusive of this node\nfor (DiscoveredContainer dc : ssd.discoverContainers()) {\n    System.out.println(dc.getIp());\n}\n\n```\n\n**Sample for connecting to SSL enabled Swarm MGR Docker host**\n\n```\nSwarmServiceDiscovery ssd = new SwarmServiceDiscovery()\n                            .swarmMgrUri(new URI(\"http[s]://myswarmmgr:237[5|6]\"))\n                            .skipVerifySsl([true | false])\n                            \n                            .addDockerNetworkName(\"my-service-net\")\n                            .addDockerServiceName(\"my-service-01\")\n                            \n                            // optional label filter\n                            .addDockerServiceLabel(\"production\");\n                        \n// get my ip on the docker overlay network\nInetAddress myIp = ssd.getMyIpAddress();\n                        \n// gets all nodes inclusive of this node\nfor (DiscoveredContainer dc : ssd.discoverContainers()) {\n    System.out.println(dc.getIp());\n}\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.swarm.service` additional verbose debugging information will appear\n\n\n## \u003ca id=\"runningexample\"\u003e\u003c/a\u003eRunning example\n\nThe best example is to check out the [.travis.yml](.travis.yml) file or browse the latest test output at\nhttps://travis-ci.org/bitsofinfo/docker-discovery-swarm-service\n\n## \u003ca id=\"building\"\u003e\u003c/a\u003eBuilding from source\n\n* From the root of this project, build a Jar : `./gradlew build`\n\n* Include the built jar artifact located at `build/libs/docker-discovery-swarm-service-[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    \n    ```\n    compile group: 'com.spotify', name: 'docker-client', version: '8.7.3'\n    compile 'org.slf4j:slf4j-api:1.7.19'\n    \n    // optional if you don't already have a SLF4j impl logger\n    //compile group: 'log4j', name: 'log4j', version: '1.2.17'\n    ```\n\n\n## \u003ca id=\"tests\"\u003e\u003c/a\u003eUnit-tests\n\n[![Build Status](https://travis-ci.org/bitsofinfo/docker-discovery-swarm-service.svg?branch=master)](https://travis-ci.org/bitsofinfo/docker-discovery-swarm-service)\n\nThere are really no traditional Java \"unit tests\" for this SPI due to its reliance on Docker. \n\nThere is however a [Travis CI test](https://travis-ci.org/bitsofinfo/docker-discovery-swarm-service) that properly\nvalidates the functionality in a real Docker swarm environment that brings up a single instance, scales it to 10 hazelcastnodes and then back down to 2 nodes. Demonstrating the proper discovery of self and peer containers in the service.\n\nSee the [.travis.yml](.travis.yml) file for the full details.\n\n\n## \u003ca id=\"related\"\u003e\u003c/a\u003eRelated info\n\n* https://docs.docker.com/engine/swarm/\n\n\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fdocker-discovery-swarm-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitsofinfo%2Fdocker-discovery-swarm-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitsofinfo%2Fdocker-discovery-swarm-service/lists"}