From c4ec25bb14f339c80ceda84eefdf3b118800539a Mon Sep 17 00:00:00 2001 From: kpoplin Date: Sun, 27 Mar 2016 06:49:28 -0700 Subject: [PATCH] Update README.md Updated for consistent pronoun usage; corrected product and company references, following our standardized naming conventions; fixed other minor grammatical errors. --- README.md | 67 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index c868c7ae..3e2b68d8 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,16 @@ [Weaveworks](http://weave.works) is the company that develops Weave - the most productive way for developers to connect, observe and control -Docker containers. To learn about our products, including getting +Docker containers. + +# Introduction +This document is intended to cover some of the more technical aspects of Weave Net. To learn about our products, including getting started tutorials, visit our [website](http://weave.works) and -[documentation](http://docs.weave.works) or continue to read about -some of the more technical aspects of Weave in this readme. +[documentation](http://docs.weave.works). -# Weave +# Weave Net -Weave creates a virtual network that connects Docker containers +Weave Net creates a virtual network that connects Docker containers deployed across multiple hosts and enables their automatic discovery. ![Weave Virtual Network](/docs/virtual-network.png?raw=true "Weave Virtual Network") @@ -26,36 +28,36 @@ regardless of where those containers are running. Similarly, existing internal systems can be exposed to application containers irrespective of their location. -![Weave Deployment](/docs/deployment.png?raw=true "Weave Deployment") +![Weave Net Deployment](/docs/deployment.png?raw=true "Weave Net Deployment") -Weave can traverse firewalls and operate in partially connected +Weave Net can traverse firewalls and operate in partially connected networks. Traffic can be encrypted, allowing hosts to be connected across an untrusted network. -With weave you can easily construct applications consisting of +With Weave Net you can easily construct applications consisting of multiple containers, running anywhere. -Weave works alongside Docker's existing (single host) networking +Weave Net works alongside Docker's existing (single host) networking capabilities, so these can continue to be used by containers. ## Installation -Ensure you are running Linux (kernel 3.8 or later) and have Docker -(version 1.6.0 or later) installed. Then install weave with +To get started, you should be running Linux (kernel 3.8 or later) and have Docker +(version 1.6.0 or later) installed. Then install Weave Net with sudo curl -L git.io/weave -o /usr/local/bin/weave sudo chmod a+x /usr/local/bin/weave For usage on OSX (with Docker Machine) you first need to [make sure that a VM is running and configured](https://docs.docker.com/installation/mac/#from-your-shell). -Then you can launch weave directly from the OSX host. +Then you can launch Weave Net directly from the OSX host. -For installing weave on other platforms, follow the [integration guides](http://weave.works/product/integrations/). +For installing Weave Net on other platforms, follow the [integration guides](http://weave.works/product/integrations/). -Weave respects the environment variable `DOCKER_HOST`, so you can run +Weave Net respects the environment variable `DOCKER_HOST`, so you can run it locally to control a weave network on a remote host. -Weave will periodically check with our servers to see if a new version is available. +Weave Net will periodically check with our servers to see if a new version is available. New versions are announced in the log. To disable this, run: ``` @@ -76,7 +78,7 @@ Say you have docker running on two hosts, accessible to each other as `$HOST1` and `$HOST2`, and want to deploy an application consisting of two containers, one on each host. -On $HOST1 we run: +On $HOST1 you would run: host1$ weave launch host1$ eval $(weave env) @@ -92,40 +94,40 @@ On $HOST1 we run: > `sudo`, since some commands modify environment entries and hence > they all need to be executed from the same shell. -The first line runs weave. The second line configures our environment +The first line runs Weave Net. The second line configures your environment so that containers launched via the docker command line are -automatically attached to the weave network. Finally, we run our +automatically attached to the weave network. Finally, you run your application container. -That's it! If our application consists of more than one container on -this host we simply launch them with `docker run` as appropriate. +That's it! If your application consists of more than one container on +this host, you can simply launch them with `docker run` as appropriate. -Next we repeat similar steps on `$HOST2`... +Next you'll repeat similar steps on `$HOST2`... host2$ weave launch $HOST1 host2$ eval $(weave env) host2$ docker run --name a2 -ti ubuntu The only difference, apart from the name of the application container, -is that we tell our weave that it should peer with the weave on +is that weave is being told that it should peer with the weave on `$HOST1` (specified as the IP address or hostname, and optional `:port`, by which `$HOST2` can reach it). NB: if there is a firewall between `$HOST1` and `$HOST2`, you must permit traffic to the weave control port (TCP 6783) and data ports (UDP 6783/6784). -Note that we could instead have told the weave on `$HOST1` to connect to +Note that you could instead have told the Weave Net instance on `$HOST1` to connect to `$HOST2`, or told both about each other. Order does not matter here; -weave automatically (re)connects to peers when they become -available. Also, we can tell weave to connect to multiple peers by -supplying multiple addresses, separated by spaces. And we can +Weave Net automatically (re)connects to peers when they become +available. You can instruct Weave Net to connect to multiple peers by +supplying multiple addresses, separated by spaces; you can also [add peers dynamically](http://docs.weave.works/weave/latest_release/features.html#dynamic-topologies). -Weave must be started once per host. The relevant container images are +Weave Net must be started once per host. The relevant container images are pulled down on demand, but if you wish you can preload them by running `weave setup` - this is particularly useful for automated deployments, and ensures that there are no delays during later operations. -Now that we've got everything set up, let's see whether our containers +Now that you've got everything set up, let's confirm that your containers can talk to each other... In the container started on `$HOST1`... @@ -144,7 +146,7 @@ Similarly, in the container started on `$HOST2`... 1 packets transmitted, 1 received, 0% packet loss, time 0ms rtt min/avg/max/mdev = 0.366/0.366/0.366/0.000 ms -So there we have it, two containers on separate hosts happily talking +So there you have it, two containers on separate hosts happily talking to each other. ## Find out more @@ -162,15 +164,14 @@ Found a bug, want to suggest a feature, or have a question? Please [file an issue](https://github.com/weaveworks/weave/issues), or post to the [Weave Users Google Group](https://groups.google.com/a/weave.works/forum/#!forum/weave-users), -which you can email at weave-users@weave.works. Or you can contact -Weaveworks directly at help@weave.works. When reporting a bug, please +which you can email at weave-users@weave.works. When reporting a bug, please include which version of weave you are running, as shown by `weave version`. -Follow on Twitter: +Follow us on Twitter: [@weaveworks](https://twitter.com/weaveworks). -Read the Weave blog: +Read the Weaveworks blog: [Weaveblog](http://weaveblog.com/). IRC: