Merge branch 'feature/#420-bash-on-windows' into develop

docs/install/linux.rst

@@ -56,8 +56,9 @@ First, you need to install all of the software on which Tabbycat depends, if you
 .. admonition:: Advanced users
   :class: tip
 
-  These instructions are for Ubuntu 14.10 and higher. If you have another distribution of Linux, we trust you'll know how to navigate the package manager for your distribution to install the dependencies.
+  These instructions are for Ubuntu 14.04 and higher. If you have another distribution of Linux, we trust you'll know how to navigate the package manager for your distribution to install the dependencies.
 
+.. _install-linux-python:
 1(a). Python
 ------------
 As of version 0.8, Tabbycat requires Python 3.4 or later.  You probably already have Python 3.4, but you'll also need the development package in order to install Psycopg2 later.  The ``venv`` module will come in handy too.  Install::
@@ -87,6 +88,7 @@ You'll need the *server-dev* package in order to install Psycopg2 later. As per
 
 If using Ubuntu <14.10 substitute "postgresql-9.3" for "postgresql-9.6" in the above commands.
 
+.. _install-linux-nodejs
 1(c). Node.js/NPM
 -----------------
   *Node.js is a JavaScript runtime.*
@@ -100,6 +102,7 @@ Tabbycat requires Node and its package manager to compile front-end dependencies
   $ sudo apt-get install -y nodejs
   $ sudo ln -s /usr/bin/nodejs /usr/bin/node
 
+.. _install-linux-source-code:
 2. Get the source code
 ======================
 
@@ -138,6 +141,7 @@ If you've used Git before, you might prefer to clone `our GitHub repository`_ in
     $ sudo -u postgres createdb mydatabasename --owner myusername
 
 
+.. _install-linux-tabbycat:
 4. Install Tabbycat
 ===================
 Almost there!

docs/install/windows.rst

@@ -8,6 +8,8 @@ Before you start, be sure to read our page on :ref:`local installations <install
 
 .. attention:: If you just want to quickly setup a copy of Tabbycat to run on Windows we reccomend :ref:`installing using Docker<install-docker>`, which will be much easier than following the instructions below.
 
+  If you have any experience with Linux, we'd recommend installing it on :ref:`Bash for Windows <install-wsl>` instead, which is much easier than the instructions below, provided that you have experience with Linux.
+
 Requisite technical background
 ==============================
 
@@ -59,6 +61,7 @@ To check that Python is installed correctly, open Windows PowerShell, type ``pyt
   - Your installation path must not have any spaces in it.
   - If that doesn't work, note that the following must be part of your ``PATH`` environment variable: ``C:\Python35;C:\Python35\Scripts`` (or as appropriate for your installation directory). Follow `the instructions here <https://www.java.com/en/download/help/path.xml>`_ to add this to your path.
 
+.. _install-windows-postgresql:
 1(b). PostgreSQL
 ----------------
   *PostgreSQL is a database management system.*
@@ -105,6 +108,7 @@ Download and run the `node.js Windows Installer (.msi) <https://nodejs.org/en/do
 
   Even better, you might like to fork the repository first, to give yourself a little more freedom to make code changes on the fly (and potentially :ref:`contribute <contributing>` them to the project).
 
+.. _install-windows-database:
 3. Set up a new database
 ========================
 

docs/install/wsl.rst

@@ -0,0 +1,93 @@
+.. _install-wsl::
+
+=====================================
+Installing Locally on Bash on Windows
+=====================================
+
+Before you start, be sure to read our page on :ref:`local installations <install-local>` to help you understand what's going on, particularly this section: :ref:`install-decision`
+
+.. attention:: If you just want to quickly setup a copy of Tabbycat to run on Windows we reccomend :ref:`installing using Docker<install-docker>`, which will be much easier than following the instructions below.
+
+Requisite technical background
+==============================
+
+`Bash on Windows is in beta <https://msdn.microsoft.com/en-us/commandline/wsl/about>`_, so you should be confident with command-line interfaces and have at least some experience with Linux. If you're not already familiar with Bash on Windows, you should be willing to familiarise yourself with it, including potentially things not mentioned in these instructions. While a background in the specific tools (Python, *etc.*) we use will make things easier for you, it's not necessary: we'll talk you through the rest.
+
+.. admonition:: Advanced users
+  :class: tip
+
+  Tabbycat is a `Django <https://www.djangoproject.com/>`_ project, so can be installed in any manner that Django projects can normally be installed. For example, if you prefer some SQL system other than PostgreSQL, you can use it so long as it's Django-compatible. Just be aware that we haven't tried it.
+
+Differences from the Linux installation
+=======================================
+
+For the most part, these instructions mirror those for doing local installations on Linux. The only difference is that, rather than installing PostgreSQL on Linux, you'll install **PostgreSQL for Windows**. The reason for this is that `PostgreSQL doesn't yet work on the Windows Subsystem for Linux <https://github.com/Microsoft/BashOnWindows/issues/61>`_. As of February 2017, there is a fix on the Windows Insider Preview Build, but it's still making its way to general availability.
+
+This has a number of consequences:
+
+1. You'll still install the PostgreSQL *client* on the Linux subsystem, using that to communicate with the server on Windows.
+2. Because you won't install the PostgreSQL server, you need to install ``libpq-dev`` instead, in order for the `psycopg2` module to work.
+3. These instructions will direct you to create the PostgreSQL role and database in **pgAdmin**, just like in the :ref:`Windows instructions <install-windows-database>`.
+
+Short version
+=============
+First, install `PostgreSQL for Windows <https://www.postgresql.org/download/windows/>`_ (on Windows, not on the subsystem for Linux). Once you've set it up, create a new role and database as instructed in the Windows instructions in section :ref:`install-windows-database`. Then, in a Bash on Windows shell:
+
+.. parsed-literal::
+
+  curl -sL https\:\/\/deb.nodesource.com/setup_5.x | sudo -E bash -    # add Node.js source repository
+  sudo apt-get install python3-dev python3-venv libpq-dev postgresql-client-9.5 nodejs
+
+  # either
+  wget https\:\/\/github.com/czlee/tabbycat/archive/|vrelease|.tar.gz
+  tar xf |vrelease|.tar.gz
+  cd tabbycat-|release|
+  # or
+  git clone https\:\/\/github.com/czlee/tabbycat.git
+  git checkout |vrelease|                                         # or master
+
+Then create local_settings.py as described in the :ref:`Linux instructions <local-settings-linux>`, then::
+
+  python3 -m venv venv
+  source venv/bin/activate
+  pip install --upgrade pip
+  pip install -r requirements_common.txt
+  npm install
+  cd tabbycat
+  dj migrate
+  dj collectstatic
+  dj createsuperuser
+  waitress-serve wsgi:application
+
+1. Install dependencies
+=======================
+
+Follow these instructions:
+
+- :ref:`install-linux-python` in the Linux instructions, on the Bash subsystem
+- :ref:`install-windows-postgresql` in the Windows instructions (in Windows)
+- :ref:`install-linux-nodejs` in the Linux instructions, on the Bash subsystem
+
+2. Get the source code
+======================
+
+Follow the section :ref:`install-linux-source-code` in the Linux instructions, on the Bash subsystem.
+
+3. Set up a new database
+========================
+
+Follow the section :ref:`install-windows-database` in the Windows instructions (in Windows).
+
+4. Install Tabbycat
+===================
+
+Follow the section :ref:`install-linux-tabbycat` in the Linux instructions, on the Bash subsystem.
+
+Starting up an existing Tabbycat instance
+=========================================
+To start your Tabbycat instance up again next time you use your computer::
+
+    $ cd /mnt/c/path/to/my/tabbycat/directory
+    $ source venv/bin/activate
+    $ cd tabbycat
+    $ waitress-serve wsgi:application