Merge pull request #8034 from stefansimik/master

Docs extended: Installation behind firewall

docs/source/getting_started/installation.rst

@@ -36,14 +36,14 @@ If you use ``pipenv``, you can install it as:
 .. code:: bash
 
     pipenv install jupyterlab
-     pipenv shell
+    pipenv shell
 
 or from a git checkout:
 
 .. code:: bash
 
     pipenv install git+git://github.com/jupyterlab/jupyterlab.git#egg=jupyterlab
-     pipenv shell
+    pipenv shell
 
 When using ``pipenv``, in order to launch ``jupyter lab``, you must activate the project's virtualenv.
 For example, in the directory where ``pipenv``'s ``Pipfile`` and ``Pipfile.lock`` live (i.e., where you ran the above commands):
@@ -51,7 +51,7 @@ For example, in the directory where ``pipenv``'s ``Pipfile`` and ``Pipfile.lock`
 .. code:: bash
 
     pipenv shell
-     jupyter lab
+    jupyter lab
 
 Docker
 ~~~~~~
@@ -114,4 +114,94 @@ A tool like `postcss <https://postcss.org/>`__ can be used to convert the CSS fi
 ``jupyterlab/build`` directory manually if desired.
 
 
+Installation problems
+~~~~~~~~~~~~~~~~~~~~~
+
+If your computer is behind corporate proxy or firewall,
+you may encounter HTTP and SSL errors due to custom security profiles managed by corporate IT departments.
+
+Example of typical error, when conda cannot connect to own repositories:
+
++ `CondaHTTPError: HTTP 000 CONNECTION FAILED for url <https://repo.anaconda.com/pkgs/main/win-64/current_repodata.json>`
+
+
+This may happen because your company can block connections to widely-used repositories in Python and JavaScript communities.
+
+Here are some widely-used sites that host packages in the Python and JavaScript open-source ecosystem. Your network adminstrator may be able to allow http and https connections to these:
+
+- \*.pypi.org
+- \*.pythonhosted.org
+- \*.continuum.io
+- \*.anaconda.com
+- \*.conda.io
+- \*.github.com
+- \*.githubusercontent.com
+- \*.npmjs.com
+- \*.yarnpkg.com
+
+Alternatively you can specify proxy user (mostly domain user with password),
+that is allowed to communicate via network. This can be easily achieved
+by setting two common environment variables: `HTTP_PROXY` and `HTTPS_PROXY`.
+These variables are automatically used by many open-source tools (like ``conda``) if set correctly.
+
+.. code:: bash
+
+    # For Windows
+    set HTTP_PROXY=http://USER:PWD@proxy.company.com:PORT
+    set HTTPS_PROXY=https://USER:PWD@proxy.comp any.com:PORT
+
+    # For Linux / MacOS
+    export HTTP_PROXY=http://USER:PWD@proxy.company.com:PORT
+    export HTTPS_PROXY=https://USER:PWD@proxy.company.com:PORT
+
+
+In case you can communicate via HTTP, but installation with ``conda`` fails
+on connectivity problems to HTTPS servers, you can disable using SSL for ``conda``.
+
+.. warning:: Disabling SSL in communication is generally not recommended and involves potential security risk.
+
+.. code:: bash
+
+    # Configure npm to not use SSL
+    conda config --set ssl_verify False
+
+
+You can do a similar thing for ``pip``.
+The approach here is to mark repository servers as trusted hosts,
+which means, SSL communication will not be required for downloading Python libraries.
+
+.. code:: bash
+
+    # Install pandas (without SSL)
+    pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org pandas
+
+
+Using the tips from above, you can handle many network problems 
+related to installing Python libraries.
+
+Many Jupyter extensions require having a working ``npm`` command,
+which is required for downloading useful Jupyter extensions or other JavaScript dependencies.
+
+Example of typical error message, when ``npm`` cannot connect to own repositories:
+
++ `ValueError: "@jupyterlab/toc" is not a valid npm package`
+
+.. code:: bash
+
+    # Set proxy for NPM
+    npm config set proxy http://USER:PWD@proxy.company.com:PORT
+    npm config set proxy https://USER:PWD@proxy.company.com:PORT
+
+    # Set default registry for NPM (optional, useful in case if common JavaScript libs cannot be found)
+    npm config set registry http://registry.npmjs.org/
+
+
+In case you can communicate via HTTP, but installation with ``npm`` fails
+on connectivity problems to HTTPS servers, you can disable using SSL for ``npm``.
+
+.. warning:: Disabling SSL in communication is generally not recommended and involves potential security risk.
+
+.. code:: bash
 
+    # Configure npm to not use SSL
+    npm set strict-ssl False