Updating contributing/install docs, fixes apache#7373

CONTRIBUTING.md

@@ -293,7 +293,35 @@ python setup.py build_sphinx
 
 ### Flask server
 
-Make sure your machine meets the [OS dependencies](https://superset.incubator.apache.org/installation.html#os-dependencies) before following these steps.
+#### OS Dependencies
+
+Make sure your machine meets the [OS dependencies](https://superset.incubator.apache.org/installation.html#os-dependencies) before following these steps. 
+
+In addition you will need to install the mysql client to get mysql_config, which is required by mysqlclient in requirements-dev.txt.
+
+For Debian/Ubuntu:
+
+```bash
+sudo apt-get install -y libmysqlclient-dev
+```
+
+For OS X via brew:
+
+```bash
+brew install mysql-client
+echo 'export PATH="/usr/local/opt/mysql-client/bin:$PATH"' >> ~/.bash_profile
+source ~/.bash_profile
+```
+
+Developers should use a virtualenv. Anaconda Python users should make sure that conda installs the virtualenv package, otherwise conda packages won't play well with packages installed by pip.
+
+```bash
+# Conda modified virtualenv on conda-forge to work with pip
+conda install --force-reinstall -y virtualenv
+
+# Otherwise pip is fine
+pip install virtualenv
+```
 
 ```bash
 # Create a virtual environemnt and activate it (recommended)
@@ -303,10 +331,11 @@ source venv/bin/activate
 # Install external dependencies
 pip install -r requirements.txt
 pip install -r requirements-dev.txt
+
 # Install Superset in editable (development) mode
 pip install -e .
 
-# Create an admin user
+# Create an admin user in the app sqlite DB at ~/.superset/superset.db
 fabmanager create-admin --app superset
 
 # Initialize the database
@@ -318,14 +347,13 @@ superset init
 # Load some data to play with
 superset load_examples
 
-# Start the Flask dev web server from inside the `superset` dir at port 8088
+# Start the Flask dev web server from inside your virtualenv.
 # Note that your page may not have css at this point.
 # See instructions below how to build the front-end assets.
-cd superset
-FLASK_ENV=development flask run -p 8088 --with-threads --reload --debugger
+FLASK_ENV=development superset run -p 8088 --with-threads --reload --debugger
 ```
 
-#### Logging to the browser console
+#### Logging to the browser console (not working)
 
 This feature is only available on Python 3. When debugging your application, you can have the server logs sent directly to the browser console:
 
@@ -345,7 +373,14 @@ app.logger.info(form_data)
 
 Frontend assets (JavaScript, CSS, and images) must be compiled in order to properly display the web UI. The `superset/assets` directory contains all NPM-managed front end assets. Note that there are additional frontend assets bundled with Flask-Appbuilder (e.g. jQuery and bootstrap); these are not managed by NPM, and may be phased out in the future.
 
-First, be sure you are using recent versions of NodeJS and npm. Using [nvm](https://github.com/creationix/nvm) to manage them is recommended.
+#### nvm and node
+
+First, be sure you are using recent versions of NodeJS and npm. Using [nvm](https://github.com/creationix/nvm) to manage them is recommended. Check the docs at the link to be sure, but at the time of writing the following would install nvm and node:
+
+```bash
+curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
+nvm install node
+```
 
 #### Prerequisite
 
@@ -389,6 +424,12 @@ npm run prod
 npm run sync-backend
 ```
 
+If you run this service from somewhere other than your local machine, you may need to add hostname value to webpack.config.js at .devServer.public specifying the endpoint at which you will access the app. For example: myhost:9001. For convenience you may want to install webpack, webpack-cli and webpack-dev-server globally so that you can run them directly:
+
+```bash
+npm install --global webpack webpack-cli webpack-dev-server
+```
+
 #### Updating NPM packages
 
 Use npm in the prescribed way, making sure that

docs/installation.rst

@@ -114,10 +114,17 @@ that the required dependencies are installed: ::
     sudo yum upgrade python-setuptools
     sudo yum install gcc gcc-c++ libffi-devel python-devel python-pip python-wheel openssl-devel libsasl2-devel openldap-devel
 
-**OSX**, system python is not recommended. brew's python also ships with pip  ::
+**Mac OS X** If possible, you should upgrade to the latest version of OS X as issues are more likely to be resolved for that version. 
+You *will likely need* the latest version of XCode available for your installed version of OS X. You should also install
+the XCode command line tools: ::
+
+    xcode-select --install
+
+System python is not recommended. Homebrew's python also ships with pip: ::
 
     brew install pkg-config libffi openssl python
-    env LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include" pip install cryptography==1.9
+    env LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include" pip install cryptography==2.4.2
+    env LDFLAGS="-L$(brew --prefix openssl)/lib" pip install mysqlclient==1.3.13
 
 **Windows** isn't officially supported at this point, but if you want to
 attempt it, download `get-pip.py <https://bootstrap.pypa.io/get-pip.py>`_, and run ``python get-pip.py`` which may need admin access. Then run the following: ::
@@ -149,6 +156,15 @@ On windows the syntax for activating it is a bit different: ::
 Once you activated your virtualenv everything you are doing is confined inside the virtualenv.
 To exit a virtualenv just type ``deactivate``.
 
+Anaconda Python's conda
+-----------------------
+
+conda environments do not work well with superset because not all required packages are available on conda-forge. This may
+change in the future. To use a virtualenv from conda, you must have installed conda's version of virtualenv which is
+patched to work with conda.
+
+    conda install --force-reinstall -y virtualenv
+
 Python's setup tools and pip
 ----------------------------
 Put all the chances on your side by getting the very latest ``pip``