[tor-commits] [community/master] Refactor docker installation instructions.

[phw at torproject.org]

commit d654c53eca0e179ef145c25a36f4917e62c154e7
Author: Philipp Winter <phw at nymity.ch>
Date:   Tue Nov 26 15:45:42 2019 -0800

    Refactor docker installation instructions.
---
 .../technical-setup/bridge/docker/contents.lr      | 50 +++++++++++++++++-----
 1 file changed, 39 insertions(+), 11 deletions(-)

diff --git a/content/relay-operations/technical-setup/bridge/docker/contents.lr b/content/relay-operations/technical-setup/bridge/docker/contents.lr
index 9c7cf44..272afcf 100644
--- a/content/relay-operations/technical-setup/bridge/docker/contents.lr
+++ b/content/relay-operations/technical-setup/bridge/docker/contents.lr
@@ -17,19 +17,30 @@ docker pull phwinter/obfs4-bridge:latest
 
 ### 2. Deploy a container
 
-We provide a Makefile that makes it easy to deploy a container.  First,
-[download the
-Makefile](https://dip.torproject.org/torproject/anti-censorship/docker-obfs4-bridge/raw/master/Makefile),
-and then run:
+We provide a Makefile that helps you deploy the container.  First,
+[download the Makefile](https://dip.torproject.org/torproject/anti-censorship/docker-obfs4-bridge/raw/master/Makefile),
+and then write your bridge configuration to a new file, bridge.sh.  Here's a
+template:
 
 ```
-make deploy OR_PORT=X PT_PORT=Y EMAIL=Z
+# Your bridge's Tor port.
+export OR_PORT=X
+# Your bridge's obfs4 port.
+export PT_PORT=Y
+# Your email address.
+export EMAIL=Z
 ```
 
 Replace `X` with your desired OR port, `Y` with your obfs4 port (make sure that
 **both** ports are forwarded in your firewall), and `Z` with your email address,
 which allows us to get in touch with you if there are problems with your bridge.
-If everything worked fine, you should see output similar to the following:
+With your bridge configuration in place, you can now deploy the container:
+
+```
+source bridge.sh && make deploy
+```
+
+You should now see output similar to the following:
 
 ```
 201fbd2b4d28e6f226978f27547edd79272871c5949bf8aab3872c983156a108
@@ -37,21 +48,38 @@ Make sure that port X and Y are forwarded in your firewall.
 ```
 
 That's it! Your container (identified by the first line of output) is now
-bootstrapping your new obfs4 bridge.  If you want to run more than one bridge on
-a single machine, run `make deploy` again, but with a different set of ports.
+bootstrapping your new obfs4 bridge.
 
-### 3. Upgrade a container
+If you want to run multiple bridges on your machine, you need to create more
+bridge configuration files with different sets of ports, and run `make deploy`
+again, like so:
+
+```
+source bridge-1.sh && make deploy
+source bridge-2.sh && make deploy
+...
+```
+
+### 3. Upgrade your container
 
 To upgrade to the latest version of our image, you need to stop your existing
-container, delete it, pull the latest image, and finally deploy it:
+container, delete it, pull the latest image, and finally deploy it again:
 
 ```
 docker stop CONTAINER_ID
 docker rm CONTAINER_ID
 docker pull phwinter/obfs4-bridge:latest
-make deploy OR_PORT=X PT_PORT=Y EMAIL=Z
+source bridge.sh && make deploy
 ```
 
+Note that your bridge's data directory (which includes its key material) is
+stored in a docker volume, so you won't lose your bridge's identity when
+upgrading to the latest docker image.  If you are running multiple bridges on
+your computer, you need to repeat this step for each bridge.  We will announce
+new image versions on the
+[tor-dev](https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev) mailing
+list.
+
 ### 4. Monitor your logs
 
 You can inspect your bridge's logs by running: