{"id":13689748,"url":"https://github.com/swarm-pack/swarm-sync","last_synced_at":"2025-05-02T06:31:13.337Z","repository":{"id":34441313,"uuid":"164573658","full_name":"swarm-pack/swarm-sync","owner":"swarm-pack","description":"GitOps for Docker Swarm","archived":false,"fork":false,"pushed_at":"2023-01-07T03:51:28.000Z","size":743,"stargazers_count":87,"open_issues_count":30,"forks_count":12,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-06T20:01:30.139Z","etag":null,"topics":["docker-swarm","gitops"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swarm-pack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-08T05:55:53.000Z","updated_at":"2024-10-30T18:00:43.000Z","dependencies_parsed_at":"2023-01-15T07:05:20.919Z","dependency_job_id":null,"html_url":"https://github.com/swarm-pack/swarm-sync","commit_stats":null,"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarm-pack%2Fswarm-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarm-pack%2Fswarm-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarm-pack%2Fswarm-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swarm-pack%2Fswarm-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swarm-pack","download_url":"https://codeload.github.com/swarm-pack/swarm-sync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251998319,"owners_count":21677971,"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":["docker-swarm","gitops"],"created_at":"2024-08-02T16:00:24.078Z","updated_at":"2025-05-02T06:31:13.001Z","avatar_url":"https://github.com/swarm-pack.png","language":"JavaScript","funding_links":[],"categories":["Community Tools"],"sub_categories":["Extra Functionality"],"readme":"# Swarm Sync\n\nGitOps, a term coined by [WeaveWorks](https://www.weave.works/blog/gitops-operations-by-pull-request), is a way to do continuous delivery and manage your environments through git using pull requests.\n\nSwarm-sync runs as a service in your Docker Swarm. It watches a Config Repo (a git repository managed by you) for changes and deploys them to your Swarm. Additionally it can watch Docker Registries for new images for your services and update you swarm Services accordingly.\n\nThe Config Repo contains a set of [Swarm Packs](https://github.com/swarm-pack/swarm-pack) and configuration values which will be used to set up your Swarm Services.\n\nThe best way to understand the Config Repo is by looking at the [**example Config Repo**](https://github.com/swarm-pack/swarm-sync-example).\n\n### Diagram\n\n\u003cpre\u003e\n                 +---------+            +---------+            +-----------+\n @               |  Code   |            |         |            | Container |\n-|-  +---------\u003e |   Repo  +-----------\u003e+   CI    +-----------\u003e+  Registry |\n/ \\   commit     |         |   build    |         |   push     |           |\n                 +---------+            +---------+            +-----------+\nDeveloper                                                            |\n                                                                     |\n                                                                     |\n                                                +--------------------+\n                                                |\n                                                |\n                                                v\n                  +---------+            +-----------+           +-----------+\n @                | Config  |            |  Swarm    |           |  Docker   |\n-|-  +---------\u003e  |   Repo  \u003c-----------\u003e+    Sync   +-----------\u003e    Swarm  |\n/ \\   commit      |         |   sync     |           |   apply   |           |\n                  +---------+            +-----------+           +-----------+              \nDeveloper\n\u003c/pre\u003e\n\n\n### Components of gitops\n\nThere are 3 main components needed to achieve our GitOps pipeline:\n\n1. **Configuration Repository** - a Git repository containing all the configuration for your Docker Swarm stacks. Example repository: [kevb/swarm-pack-example](https://github.com/kevb/swarm-sync-example)\n\n2. **Container Registry** - A Docker registry to push our application images to (hopefully from a CI somewhere else)\n\n3. **SwarmSync** - SwarmSync will be running inside your Swarm as a service and will be configured to point to the other 2 components.\n\n### Swarm-Pack\n\nSwarm-Sync relies on [Swarm Pack](https://github.com/swarm-pack/swarm-pack) to compile and deploy services from templates. An understanding of swarm-pack is required to use swarm-sync, so if you haven't already take a look there.\n\n### Quick-start guide\n\n1. Fork the repo https://github.com/swarm-pack/swarm-sync-example - this guide will use this URL, but you should replace with your own fork and re-configure your own desired config.\n\n2. Create a config file for swarm-sync, similar to this one:\n\n```yaml\nswarm-sync:\n\n  # Stacks in target for this swarm-sync instance\n  stacks:\n    - nonprod\n\n  # Update frequency for polling repo and image registry for changes (ms)\n  # Below 1 minute not recommended\n  updateInterval: 60000\n\n  # Git details for your Swarm Configuration Repository\n  git:\n    url: https://github.com/swarm-pack/swarm-sync-example\n    branch: master\n\n  # Common config with swarm-pack\n  docker:\n    socketPath: /var/run/docker.sock\n  repositories:\n    - name: official\n      url: https://github.com/swarm-pack/repository\n```\n\nUpload this file to a manager node in your Swarm\n\n3. On the manager node, run\n\n```\ndocker run -it \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n -v /path/to/swarm-sync.yml:/etc/swarm-sync.yml \\\n kevbuk/swarm-sync --bootstrap\n```\n\nThis uses the \"--bootstrap\" flag for swarm-sync, meaning it will not run as a daemon. That's because in our example config repo we have a swarm-pack configured for swarm-sync, so it will be deployed as a service. Make sure the swarm-sync config is the same inside your Config Repo values.\n\n4. Check your desired services are now running on your Swarm\n\n```bash\ndocker service ls\n```\n\n5. Push a change to your config repo, and check that the services update themselves within 5 minutes!\n\n### Stacks\n\nStacks are a way to namespace things, and identify what is in scope for a particular instance of Swarm Sync.\n\nFor example, you might have 2 Swarms: **prod** and **nonprod**. One approach is to create corresponding Stacks in your config repo at `stacks/prod` and `stacks/nonprod`. Each Swarm has an instance of swarm-sync with different config files. In your ***prod*** Stack instance, you would have:\n```yaml\nstacks:\n  - prod\n```\n\nIn your **nonprod** instance you'd have\n```yaml\nstacks:\n  - nonprod\n```\n\nWith this configuration, the stack defined in `stacks/nonprod/stack.yml` will be synced to your **nonprod** Swarm and the stack defined in `stacks/prod/stack.yml` will be synced to your **prod** Swarm.\n\n### Configuration\n\nConfig file should be mounted at /etc/swarm-sync.yml and Docker Config or Docker Secret is recommended for this.\n\n### Registry authentication\n\nIf watching for image updates in a private docker registry, you will need to define authentication credentials.\n\nThis is done by mounting a docker secret matching the hostname of the registry at `/run/secrets/registries/[hostname]`.\n\nThe secret should be a yml file in the following format:\n\n```\nusername: xxx\npassword: xxx\n```\n\nFor example, to authenticate docker.example.com, we mount the following secret to `/run/secrets/registries/docker.example.com`:\n\n```\nusername: example\npassword: changeme\n```\n\n## Development\n\nNode v11.9.0\nYarn v1.7.0\n\nInstall dependencies\n\n```bash\nyarn install\n```\n\nStart server development\n\n```bash\nyarn start:dev\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarm-pack%2Fswarm-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswarm-pack%2Fswarm-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswarm-pack%2Fswarm-sync/lists"}