improve compose guide

[rade]

(left over from #178)

Beyond just using the proxy, there is the option of using the Weave Docker Network plugin, via,

networks: default: driver: weavemesh

but getting containers to use weaveDNS that way seems a bit of a faff. We need to work out whether there is a sane way to do it.

Finally, one may want to configure multiple networks, and place containers on them. compose v2 allows that, so some examples of doing that with weave networking would be good.

Overall, we need to provide users with some guidance here on what route to choose based on what they are trying to do.

One final request: Can we please, please, publish a guide or blog post with the minimal weave+compose setup. AFAICT it requires just 6 steps:

download weave + chmod
download compose + chmod
create docker-compose.yml file like the one from #178
weave launch
eval $(weave env)
docker-compose up -d

[errordeveloper]

Yes, I think there is a need for a simple compose+plugin guide.

[rade]

We need the simplest possible compose multi-host example, probably using docker-machine.

[rade]

Also, we should link to, or perhaps even inline, the docker-compose file, so people who are just looking at the guide for inspiration/guidance, rather than following it, have something to go on.

[rade]

In weaveworks/weave#2402 we identified at least four ways to use compose v2 with weave:

1. via the proxy, using "network_mode: bridge" service stanzas. Doesn't require a docker cluster. Uses weaveDNS.
2. via the plugin, using "networks: - weave" and "dns: ..." and "dns_search: ..." service stanzas and "networks: weave: external: true" networks stanza. This is using the default 'weave' network for everything. Doesn't require a docker cluster. Uses weaveDNS.
3. via the plugin, using "networks: default: driver: weave". This is placing all containers on a user-defined network using the 'weave' driver. Requires a docker cluster. Uses docker's DNS.
4. via the plugin, using "networks: - {name}" service stanzas and "networks: {name} driver: weave" network stanza. As 3 but with the ability to place containers on different/multiple networks. Requires a docker cluster. Uses docker's DNS.

3 and 4 can be augmented with the dns/dns_search stanzas from 2 to use weaveDNS.

[rade]

networks:
  default:
    external:
      name: weave

is a variation on 2, rather than setting it for each individual service. The dns and dns_search stanzas must still be specified per service though.

[rade]

Users keep tripping over this. They are evidently not finding the existing guide (possibly because it is part 3 of an overarching enormous guide), or don't know how to apply it to their situation (possibly because the guide itself doesn't actually show the compose file or explain how the weave-net-enabling stanzas work).

I suggest a dedicated guide that explains the various options above. cc @lukemarsden

[serefacet]

@rade if we use weave plugin approach , reverse dns will be a problem.

As you know after Docker v1.10 embedded docker dns is launched. Additional dns servers passed with dns parameters are managed by embedded docker dns in user-defined networks ( weave is one of the user-defined network ) so we will see that /etc/resolv.conf files of docker containers won't be updated. It will only contain 127.0.0.11 nameserver which belongs to embedded Docker DNS.

Then, if we lookup reverse dns of one ip , we will get docker container name as response from embedded Docker DNS which may cause some correlation problems.

The flawless solution is to set network_mode: "bridge" in every service for disabling Embedded Docker DNS, specifying dns, dns_search , hostname values according to weave convention, then pass weave socket address as host parameter in order to trigger docker-compose with Weave Proxy

With this approach, embedded Docker DNS will be disabled, /etc/resolv.conf will be updated and weaveDNS will be solely used for dns lookups.

[rade]

A user (and us) have just been bitten again by the absence of this guide :(

[abuehrle]

It is written @rade and it sits in a pull request. Just waiting for someone to review.

[rade]

it sits in a pull request.

where?

[abuehrle]

https://github.com/weaveworks/guides/pull/211

Thanks!