{"id":13656532,"url":"https://github.com/hseeberger/constructr","last_synced_at":"2025-04-23T22:31:06.877Z","repository":{"id":57730518,"uuid":"44397606","full_name":"hseeberger/constructr","owner":"hseeberger","description":"Coordinated (etcd, ...) cluster construction for dynamic (cloud, containers) environments","archived":true,"fork":false,"pushed_at":"2018-03-12T09:41:37.000Z","size":346,"stargazers_count":212,"open_issues_count":14,"forks_count":37,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-08-02T05:05:44.053Z","etag":null,"topics":["akka","akka-cluster","etcd"],"latest_commit_sha":null,"homepage":"","language":"Scala","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/hseeberger.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":"2015-10-16T16:31:20.000Z","updated_at":"2024-06-18T17:08:07.000Z","dependencies_parsed_at":"2022-09-13T08:41:31.582Z","dependency_job_id":null,"html_url":"https://github.com/hseeberger/constructr","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hseeberger%2Fconstructr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hseeberger%2Fconstructr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hseeberger%2Fconstructr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hseeberger%2Fconstructr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hseeberger","download_url":"https://codeload.github.com/hseeberger/constructr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223936098,"owners_count":17228092,"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":["akka","akka-cluster","etcd"],"created_at":"2024-08-02T05:00:22.667Z","updated_at":"2024-11-10T09:31:34.694Z","avatar_url":"https://github.com/hseeberger.png","language":"Scala","funding_links":[],"categories":["Extension"],"sub_categories":[],"readme":"# ConstructR #\n\n[![Join the chat at https://gitter.im/hseeberger/constructr](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/hseeberger/constructr?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nConstructR is for bootstrapping (construction) an [Akka](http://akka.io) cluster by using a coordination service.\n\nDisambiguation: Despite the similar name, ConstructR is not related to [Lightbend ConductR](http://www.lightbend.com/products/conductr).\n\nConstructR utilizes a key-value coordination service like etcd to automate bootstrapping or joining a cluster. It stores each member node under the key `/constructr/$clusterName/nodes/$address` where `$clusterName` is for disambiguating multiple clusters and `$address` is a Base64 encoded Akka `Address`. These keys expire after a configurable time in order to avoid stale information. Therefore ConstructR refreshes each key periodically.\n\nIn a nutshell, ConstructR is a state machine which first tries to get the nodes from the coordination service. If none are available it tries to acquire a lock, e.g. via a CAS write for etcd, and uses itself or retries getting the nodes. Then it joins using these nodes as seed nodes. After that it adds its address to the nodes and starts the refresh loop:\n\n```\n                  ┌───────────────────┐              ┌───────────────────┐\n              ┌──▶│   GettingNodes    │◀─────────────│BeforeGettingNodes │\n              │   └───────────────────┘    delayed   └───────────────────┘\n              │             │     │                            ▲\n  join-failed │   non-empty │     └──────────────────────┐     │ failure\n              │             ▼               empty        ▼     │\n              │   ┌───────────────────┐              ┌───────────────────┐\n              └───│      Joining      │◀─────────────│      Locking      │\n                  └───────────────────┘    success   └───────────────────┘\n                            │\n              member-joined │\n                            ▼\n                  ┌───────────────────┐\n                  │    AddingSelf     │\n                  └───────────────────┘\n                            │     ┌────────────────────────────┐\n                            │     │                            │\n                            ▼     ▼                            │\n                  ┌───────────────────┐              ┌───────────────────┐\n                  │ RefreshScheduled  │─────────────▶│    Refreshing     │\n                  └───────────────────┘              └───────────────────┘\n```\n\nIf something goes finally wrong when interacting with the coordination service, e.g. a permanent timeout after a configurable number of retries, ConstructR terminates its `ActorSystem` in the spirit of \"fail fast\".\n\n``` scala\n// All releases including intermediate ones are published here,\n// final ones are also published to Maven Central.\nresolvers += Resolver.bintrayRepo(\"hseeberger\", \"maven\")\n\nlibraryDependencies ++= Vector(\n  \"de.heikoseeberger\" %% \"constructr\" % \"0.19.0\",\n  \"de.heikoseeberger\" %% \"constructr-coordination-etcd\" % \"0.19.0\", // in case of using etcd for coordination\n  ...\n)\n```\n\nSimply add the `ConstructrExtension` to the `extensions` configuration setting:\n\n```\nakka.extensions = [de.heikoseeberger.constructr.ConstructrExtension]\n```\n\nThis will start the `Constructr` actor as a system actor. Alternatively start it yourself as early as possible if you feel so inclined.\n\nThe following listing shows the available configuration settings with their defaults:\n\n```\nconstructr {\n  coordination {\n    host = localhost\n    port = 2379\n  }\n\n  coordination-timeout    = 3 seconds  // Maximum response time for coordination service (e.g. etcd)\n  join-timeout            = 15 seconds // Might depend on cluster size and network properties\n  abort-on-join-timeout   = false      // Abort the attempt to join if true; otherwise restart the process from scratch\n  max-nr-of-seed-nodes    = 0          // Any nonpositive value means Int.MaxValue\n  nr-of-retries           = 2          // Nr. of tries are nr. of retries + 1\n  refresh-interval        = 30 seconds // TTL is refresh-interval * ttl-factor\n  retry-delay             = 3 seconds  // Give coordination service (e.g. etcd) some delay before retrying\n  ttl-factor              = 2.0        // Must be greater or equal 1 + ((coordination-timeout * (1 + nr-of-retries) + retry-delay * nr-of-retries)/ refresh-interval)!\n  ignore-refresh-failures = false      // Ignore failures once machine is already in \"Refreshing\" state. It prevents from FSM being terminated due to exhausted number of retries.\n\n}\n```\n\n## Coordination\n\nConstructR comes with out-of-the-box support for etcd: simply depend on the \"constructr-coordination-etcd\" module. If you want to use some other coordination backend, e.g. Consul, simply implement the `Coordination` trait from the \"constructr-coordination\" module and make sure to provide the fully qualified class name via the `constructr.coordination.class-name` configuration setting.\n\n### Community Coordination Implementations\n\nThere are some implementations for other coordination backends than etcd:\n\n* [Tecsisa/constructr-consul](https://github.com/Tecsisa/constructr-consul): This library enables to use Consul as cluster coordinator in a ConstructR based cluster.\n* [everpeace/constructr-redis](https://github.com/everpeace/constructr-redis): This library enables to use Redis as cluster coordinator in a ConstructR based cluster.\n* [typesafehub/constructr-zookeeper](https://github.com/typesafehub/constructr-zookeeper): This library enables to use ZooKeeper as cluster coordinator in a ConstructR based cluster.\n\n## Testing\n\netcd must be running, e.g.:\n\n```\ndocker run \\\n  --detach \\\n  --name etcd \\\n  --publish 2379:2379 \\\n  quay.io/coreos/etcd:v2.3.8 \\\n  --listen-client-urls http://0.0.0.0:2379 \\\n  --advertise-client-urls http://192.168.99.100:2379\n```\n\n## Contribution policy ##\n\nContributions via GitHub pull requests are gladly accepted from their original author. Along with any pull requests, please state that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.\n\nPlease make sure to follow these conventions:\n- For each contribution there must be a ticket (GitHub issue) with a short descriptive name, e.g. \"Respect seed-nodes configuration setting\"\n- Work should happen in a branch named \"ISSUE-DESCRIPTION\", e.g. \"32-respect-seed-nodes\"\n- Before a PR can be merged, all commits must be squashed into one with its message made up from the ticket name and the ticket id, e.g. \"Respect seed-nodes configuration setting (closes #32)\"\n\n## License ##\n\nThis code is open source software licensed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhseeberger%2Fconstructr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhseeberger%2Fconstructr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhseeberger%2Fconstructr/lists"}