From f036a59b4f1a3466aea776df0f47fe262f4c06e7 Mon Sep 17 00:00:00 2001
From: Christie Koehler <ck@christi3k.net>
Date: Sun, 27 Nov 2016 17:06:41 -0800
Subject: [PATCH] Move details about configuring a proxy.

---
 docs/dev-env-first-time-contributors.md | 59 +++++++++++++++++++------
 docs/dev-overview.md                    |  2 +-
 2 files changed, 46 insertions(+), 15 deletions(-)

diff --git a/docs/dev-env-first-time-contributors.md b/docs/dev-env-first-time-contributors.md
index 5f474cb447..19a197d387 100644
--- a/docs/dev-env-first-time-contributors.md
+++ b/docs/dev-env-first-time-contributors.md
@@ -16,6 +16,7 @@ Contents:
 * [Step 3: Start the dev environment](#step-3-start-the-dev-environment)
 * [Step 4: Developing](#step-4-developing)
 * [Troubleshooting & Common Errors](#troubleshooting-common-errors)
+* [Specifying a proxy](#specifying-a-proxy)
 
 **If you encounter errors installing the Zulip development environment,** check
 [Troubleshooting & Common Errors](#troubleshooting-common-errors). If that
@@ -37,10 +38,8 @@ When reporting your issue, please include the following information:
 
 Installing the Zulip dev environment requires downloading several
 hundred megabytes of dependencies. You will need an active internet
-connection throughout the entire installation processes. (See
-[Specifying a
-proxy](brief-install-vagrant-dev.html#specifying-a-proxy) if you need
-a proxy to access the internet.)
+connection throughout the entire installation processes. (See [Specifying a
+proxy](#specifying-a-proxy) if you need a proxy to access the internet.)
 
 
 - **All**: 2GB available RAM, Active broadband internet connection.
@@ -251,12 +250,11 @@ does the following:
   downloads all required dependencies, sets up the python environment for
   the Zulip dev environment, and initializes a default test database.
 
-You will need an active internet connection during the entire
-processes. (See [Specifying a
-proxy](brief-install-vagrant-dev.html#specifying-a-proxy) if you need
-a proxy to access the internet.) And if you're running into any
-problems, please come chat with us [in the `provision` stream of our
-developers' chat](https://chat.zulip.org/#narrow/stream/provision).
+You will need an active internet connection during the entire processes. (See
+[Specifying a proxy](#specifying-a-proxy) if you need a proxy to access the
+internet.) And if you're running into any problems, please come chat with us
+[in the `provision` stream of our developers'
+chat](https://chat.zulip.org/#narrow/stream/provision).
 
 Once `vagrant up` has completed, connect to the dev environment with `vagrant
 ssh`:
@@ -665,10 +663,10 @@ that failed.  Once you've resolved the problem, you can rerun
 `tools/provision.py` to proceed; the provisioning system is designed
 to recover well from failures.
 
-The zulip provisioning system is generally highly reliable; the most
-common cause of issues here is a poor network connection (or one where
-you need a proxy to access the Internet and haven't
-[configured the development environment to use it](brief-install-vagrant-dev.html#specifying-a-proxy).
+The zulip provisioning system is generally highly reliable; the most common
+cause of issues here is a poor network connection (or one where you need a
+proxy to access the Internet and haven't [configured the development
+environment to use it](#specifying-a-proxy).
 
 Once you've provisioned successfully, you'll get output like this:
 ```
@@ -786,3 +784,36 @@ patching file bundler.rb
 #### Permissions errors when running the test suite in LXC
 
 See ["Possible testing issues"](testing.html#possible-testing-issues).
+
+### Specifying a proxy
+
+If you need to use a proxy server to access the Internet, you will
+need to specify the proxy settings before running `Vagrant up`.
+First, install the Vagrant plugin `vagrant-proxyconf`:
+
+```
+vagrant plugin install vagrant-proxyconf.
+```
+
+Then create `~/.zulip-vagrant-config` and add the following lines to
+it (with the appropriate values in it for your proxy):
+
+```
+HTTP_PROXY http://proxy_host:port
+HTTPS_PROXY http://proxy_host:port
+NO_PROXY localhost,127.0.0.1,.example.com
+```
+
+Now run `vagrant up` in your terminal to install the development
+server. If you ran `vagrant up` before and failed, you'll need to run
+`vagrant destroy` first to clean up the failed installation.
+
+You can also change the port on the host machine that Vagrant uses by
+adding to your `~/.zulip-vagrant-config` file.  E.g. if you set:
+
+```
+HOST_PORT 9971
+```
+
+(and halt and restart the Vagrant guest), then you would visit
+http://localhost:9971/ to connect to your development server.
diff --git a/docs/dev-overview.md b/docs/dev-overview.md
index 10fd62b523..96f2f0685f 100644
--- a/docs/dev-overview.md
+++ b/docs/dev-overview.md
@@ -84,6 +84,6 @@ at our tips for [developing remotely][dev-remote].
 [install-vagrant]: dev-env-first-time-contributors.html
 [self-install-remote]: #installing-remotely
 [self-slow-internet]: #slow-internet-connections
-[configure-proxy]: brief-install-vagrant-dev.html#specifying-a-proxy
+[configure-proxy]: dev-env-first-time-contributors.html#specifying-a-proxy
 [using-dev-env]: using-dev-environment.html
 [testing]: testing.html