{"id":19367130,"url":"https://github.com/abailly/multi-host-docker","last_synced_at":"2025-08-21T02:05:17.813Z","repository":{"id":66589853,"uuid":"59858321","full_name":"abailly/multi-host-docker","owner":"abailly","description":"Code for setting up multi-host docker with private networking","archived":false,"fork":false,"pushed_at":"2016-10-24T11:02:08.000Z","size":41,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-23T14:41:57.968Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abailly.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-05-27T19:26:40.000Z","updated_at":"2023-11-04T09:18:13.000Z","dependencies_parsed_at":"2023-05-29T11:00:27.623Z","dependency_job_id":null,"html_url":"https://github.com/abailly/multi-host-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/abailly/multi-host-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abailly%2Fmulti-host-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abailly%2Fmulti-host-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abailly%2Fmulti-host-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abailly%2Fmulti-host-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abailly","download_url":"https://codeload.github.com/abailly/multi-host-docker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abailly%2Fmulti-host-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271415496,"owners_count":24755639,"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","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-10T07:48:18.487Z","updated_at":"2025-08-21T02:05:17.809Z","avatar_url":"https://github.com/abailly.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-host Docker Networking using OpenVSwitch\n\nThis repository contains Haskell code for provisioning and configuring a bunch of machines to run docker over a virtual network overlaid over actual network, using [OpenVSwitch](https://github.com/openvswitch/ovs/) to route packets across bridges and GRE tunnels. The \"theory\" behind this configuration is beyond the scope of this README, and beyond my capabilities and knowledge, but the basic principle is quite simple:\n\n* Use OpenSwitch to manage a *bridge* network interface,\n* Plug docker into that bridge so that created containers use it,\n* Create [GRE tunnel](http://lartc.org/howto/lartc.tunnel.gre.html)s between each managed hosts to route packets between containers.\n\n# Documentation\n\n## Building\n\nThis code relies on a fork of the excellent configuration management tool [propellor](http://propellor.branchable.com) which is linked to the main repository as a [git submodule]() To retrieve it:\n\n```\n$ git submodules init\n$ git submodules update\n```\n\nThis repository contains Haskell code. It uses [stack](http://docs.haskellstack.org) for building:\n\n```\n$ stack setup\n$ stack build\n```\n\nThis should give you an executable named `multi-host-docker-network` somewhere in your `.stack-work` directory.\n\n## Running\n\nThe `multi-host-docker-network` executable can be used to do one the following *actions*:\n\n* Provision number of hosts on [DigitalOcean](http://digitalocean.com) using [hdo](https://github.com/capital-match/hdo), a Haskell client for DO,\n* Build locally using [docker](http://docker.io) a Propellor-based configuration program to setup those hosts (or any host to which you have SSH access to),\n* Run built Propellor-based configuration program on remote hosts,\n* Build locally an [OpenVSwitch](https://github.com/openvswitch/ovs/) version compatible with remote hosts (assume Ubuntu...).\n\nHere is an example workflow. First, let's build the openvswitch Debian packages that we will need to configure our remote hosts:\n\n```\n$ multi-host-docker-network buildopenvswitch\nSending build context to Docker daemon  2.56 kB\nStep 1 : FROM ubuntu:trusty\n ---\u003e ffbf13a52255\nStep 2 : RUN apt-get update \u0026\u0026 apt-get install -y build-essential fakeroot debhelper                         autoconf automake bzip2 libssl-dev                         openssl graphviz python-all procps                         python-qt4 python-zopeinterface                         python-twisted-conch libtool\n ---\u003e Using cache\n ---\u003e ba197aaa1f2c\nStep 3 : RUN apt-get install -y wget\n ---\u003e Using cache\n ---\u003e e84ee1d34f11\nStep 4 : RUN wget -O - http://openvswitch.org/releases/openvswitch-2.3.1.tar.gz | tar xzf -\n[... quite a few minutes later ...]\nSuccessfully built b04a2ece350d\n1021+1 records in\n1021+1 records out\n523114 bytes (523 kB) copied, 0.0324031 s, 16.1 MB/s\n```\n\nThis should leave a bunch of `.deb` files in the current directory.\n\nThen we can provision and configure a bunch of hosts. Let's configure 3 machines:\n\n```\n$ multi-host-docker-network createdroplets --numberOfDroplets 3 --userKey 429079 --compilePropellor --deployPropellor\nCreating 3 hosts\ncreating host 2 with AUTH_KEY Just \"somekey\"\ncreating host 1 with AUTH_KEY Just \"somekey\"\ncreating host 3 with AUTH_KEY Just \"somekey\"\nwaiting for droplet host1 to become Active: 60s\nwaiting for droplet host2 to become Active: 60s\nwaiting for droplet host3 to become Active: 60s\nwaiting for droplet host1 to become Active: 59s\n[...quite lengthy too...]\n146.185.173.222 overall ... done\n```\n\nThe `--userKey` parameter is of course specific to one's configuration on Digital Ocean. To provision the droplets, define an environment variable `AUTH_TOKEN` containing authentication token for DO API access. Note the flags used:\n\n* `--compilePropellor` means we will run local docker-based compilation of configuration program to be sent for execution on remote hosts,\n* `--deployPropellor` means we will actually run deployment on the built hosts.\n\nIt is also possible to run propellor build and run separately:\n\n* `multi-host-docker-network buildpropellor`: Build a `propell` executable by running `stack build` inside current directory. Can be customized if one needs to build something different, \n* `multi-host-docker-network runpropellor --allHosts 1.2.3.4 --allHosts 2.3.4.5 --allHosts 3.4.5.6 --hostname 2.3.4.5`: run propellor configuration on given remote `hostname` passing the addresses/names of all the other hosts in the \"cluster\". It is important to pass exactly the same list to all configured hosts as this is used to define the GRE interfaces names in a way that matches pair of hosts.\n\n## Testing\n\nThe configured hosts should be rebooted before testing configuration in order to ensure interfaces are correctly setup. Alternatively, one needs to do the following after propellor configuration has run:\n\n* `service docker stop` to stop running docker: We will change its configuration and interface,\n* `ip link delete docker0`: remove existing `docker0` interface created initially when we first installed docker,\n* `ifup br0`: Start OVS bridge interface and bind GRE ports,\n* `ifup docker0`: Start new docker interface,\n* `service docker start`: Start docker.\n\n\nThen log into on one of the remote hosts:\n\n```\n# docker run -ti ubuntu:trusty bash\nroot@e17699213c7e:/# ip addr eth0\n7: eth0: \u003cBROADCAST,MULTICAST,UP,LOWER_UP\u003e mtu 1462 qdisc noqueue state UP group default \n    link/ether 02:42:ac:11:02:00 brd ff:ff:ff:ff:ff:ff\n    inet 172.17.2.0/16 scope global eth0\n       valid_lft forever preferred_lft forever\n    inet6 fe80::42:acff:fe11:200/64 scope link \n    valid_lft forever preferred_lft forever\n```\n\nlog into another remote host:\n\n```\n# docker run -ti ubuntu:trusty bash\nroot@23a4e9cbab72:/# ip addr\n7: eth0: \u003cBROADCAST,MULTICAST,UP,LOWER_UP\u003e mtu 1462 qdisc noqueue state UP group default \n    link/ether 02:42:ac:11:03:00 brd ff:ff:ff:ff:ff:ff\n    inet 172.17.3.0/16 scope global eth0\n       valid_lft forever preferred_lft forever\n    inet6 fe80::42:acff:fe11:300/64 scope link \n       valid_lft forever preferred_lft forever\nroot@23a4e9cbab72:/# ping 172.17.2.0\nPING 172.17.2.0 (172.17.2.0) 56(84) bytes of data.\n64 bytes from 172.17.2.0: icmp_seq=1 ttl=64 time=0.569 ms\n64 bytes from 172.17.2.0: icmp_seq=2 ttl=64 time=0.485 ms\n```\n\nand in the first host:\n\n```\nroot@e17699213c7e:/# ping 172.17.3.0\nPING 172.17.3.0 (172.17.3.0) 56(84) bytes of data.\n64 bytes from 172.17.3.0: icmp_seq=1 ttl=64 time=2.26 ms\n64 bytes from 172.17.3.0: icmp_seq=2 ttl=64 time=0.681 ms\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabailly%2Fmulti-host-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabailly%2Fmulti-host-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabailly%2Fmulti-host-docker/lists"}