Merge pull request #190 from cypress-io/document-cypress-binary-versi…

…on-121 document CYPRESS_BINARY_VERSION close #121
cypress-io · Nov 1, 2017 · f0d76c0 · f0d76c0
2 parents 7dd0cae + cf997fa
commit f0d76c0
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 0 deletions.
diff --git a/source/guides/getting-started/installing-cypress.md b/source/guides/getting-started/installing-cypress.md
@@ -108,3 +108,28 @@ By installing Cypress through `npm` you also get access to many other CLI comman
 As of version `0.20.0` Cypress is also a fully baked `node_module` you can require in your node scripts.
 
 You can {% url 'read more about the CLI here' command-line %}.
+
+# Advanced installation
+
+If the normal `npm install cypress` command does not work for some reason (like a corporate proxy not allowing downloading the Cypress binary from the `https://cdn.cypress.io` server), you still have a workaround. The installer can override the version and/or path of the binary to download via the `CYPRESS_BINARY_VERSION` environment variable. You have three choices:
+
+1. Install a different binary version from the {% url "`cypress` npm package" https://www.npmjs.com/package/cypress %} version. For example, to install the `cypress` npm package version `1.0.3` with the binary `1.0.1` version use this command:
+
+    ```shell
+    CYPRESS_BINARY_VERSION=1.0.1 npm install [email protected]
+    ```
+
+2. Install the Cypress binary from the given URL. For example, you can download the Cypress binary from our CDN server `https://download.cypress.io/desktop` and place it on our company's server. Then use the following command:
+
+    ```shell
+    CYPRESS_BINARY_VERSION=https://company.domain.com/cypress.zip npm install cypress
+    ```
+
+3. Download the Cypress binary zip file and install it from a local file. In the example below, we download the version `1.0.2` of the binary for the Mac OS and save it as a local file `cypress.zip`. Then we install the latest `cypress` npm package version and the downloaded zip file.
+
+    ```shell
+    curl -O https://cdn.cypress.io/desktop/1.0.2/osx64/cypress.zip
+    CYPRESS_BINARY_VERSION=cypress.zip npm install cypress
+    ```
+
+In all cases, the fact that the binary was installed from a custom location *is not saved* in your `package.json` file. Every repeated installation would have to use the same environment variable to install the same binary.
diff --git a/source/guides/guides/continuous-integration.md b/source/guides/guides/continuous-integration.md
@@ -143,6 +143,8 @@ You can set any configuration value as an environment variable. This overrides v
 - `CYPRESS_BASE_URL`
 - `CYPRESS_VIDEO_COMPRESSION`
 - `CYPRESS_REPORTER`
+- `CYPRESS_VERSION`
+- `CYPRESS_BINARY_VERSION`
 
 {% note info %}
 Refer to the {% url 'configuration' configuration#Environment-Variables %} for more examples.

diff --git a/source/guides/references/changelog.md b/source/guides/references/changelog.md
@@ -25,6 +25,7 @@ comments: false
 - Cypress binaries can now be pointed to a staging environment with `CYPRESS_ENV=staging`. Fixes {% issue 813 %}.
 - The Desktop GUI displays the scrollbar correctly when the update banner is displayed. Fixes {% issue 803 %}.
 - The branch name is now properly collected when recording in Buildkite CI. Fixes {% issue 777 %}.
+- You can install the Cypress binary from any URL or file path using the {% url "`CYPRESS_BINARY_VERSION` environment variable" installing-cypress#Advanced-installation %}. Closes {% issue 701 %}.
 
 **Documentation Changes:**