Squashed commit of the following:

commit fd1ab6f
Author: Philip Belesky <[email protected]>
Date:   Sun Feb 5 23:37:47 2017 +1100

    Finalise docker instructions + don’t load from LOCAL_SETTINGS when running in Docker

commit 3571403
Author: Philip Belesky <[email protected]>
Date:   Sun Feb 5 22:28:05 2017 +1100

    Get static files working on windows

commit cb17ca8
Author: Philip Belesky <[email protected]>
Date:   Sun Feb 5 21:34:53 2017 +1100

    Shift postgres data to a volume to get things working on windows

commit 2f42a85
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 20:54:29 2017 +1100

    Actually no need to worry about exposing ports and the like

commit 677e0c1
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 20:48:04 2017 +1100

    Update install docs

commit 0d08953
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 19:28:17 2017 +1100

    Update CHANGELOG with Docker functions

commit 28a4cf0
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 19:13:55 2017 +1100

    Add windows .bat file and change port to prevent collisions

commit e1c6e64
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 13:41:54 2017 +1100

    WIP on install instructions

commit 9fdf63c
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 13:01:48 2017 +1100

    Switch to waitress; only compile assets once

commit e9e7bc6
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 12:46:19 2017 +1100

    Working build!

commit cb011ac
Author: Philip Belesky <[email protected]>
Date:   Sat Feb 4 12:29:38 2017 +1100

    Basic setup works (although not postgres roles)

commit 573891c
Author: Philip Belesky <[email protected]>
Date:   Fri Feb 3 19:55:20 2017 +1100

    Initial WIP

.dockerignore

@@ -0,0 +1,10 @@
+# Copying this over will mess up database settings
+*/*/local_settings.py
+
+# Dependencies
+node_modules/
+venv/
+
+# Compilations
+tabbycat/staticfiles/
+docs/

.gitignore

@@ -11,7 +11,6 @@ tabbycat/static/fonts/
 
 # Dependencies
 node_modules
-bower_components
 
 # Data to ignore
 data/*
@@ -24,6 +23,9 @@ data/*
 !data/presets/
 !data/fixtures/
 
+# Docker
+dbdata
+
 # Docs
 docs/site/
 issues-*.html

CHANGELOG.rst

@@ -10,7 +10,8 @@ Change Log
 - Started some basic infrastructure for creating Tabbycat translations
 - Separated venue groups from venue constraint categories
 - Added the ability to import 'demo' data when creating a new tournament
-- Added a more explicit donations link and dedicated page along with licence clarifications that outline when donations are expected.
+- Added the ability to dramatically simplify the process of setup Tabbycat locally on all operating systems using Docker
+- Added a more explicit donations link and dedicated page along with license clarifications that outline when donations are expected.
 
 
 1.1.7

CONTRIBUTING.rst

@@ -2,7 +2,7 @@
 Contributing
 ============
 
-Contributions are welcome, and are greatly appreciated! Every little bit helps, and credit will be given. `Join our Facebook group <https://www.facebook.com/groups/tabbycat.debate/>`_ if you have any questions about how to get started contributing.
+Contributions are welcome, and are greatly appreciated! Every little bit helps, and credit will be given. Feel free to `join our Facebook group <https://www.facebook.com/groups/tabbycat.debate/>`_ if you have any questions about how to get started.
 
 Bug reports
 ===========
@@ -16,11 +16,9 @@ Please report bugs by opening a new issue in our `GitHub repository <https://git
 Getting started
 ===============
 
-.. important:: We are using the `git-flow workflow <http://danielkummer.github.io/git-flow-cheatsheet/>`_, so please submit any pull requests against the **develop branch** (and not master).
-
-- Generally we prefer that features and bug fixes are submitted as pull requests on their own branch (as described in the git-flow process)
+- To easily test your changes to Tabbycat you probably want a working :ref:`local install <install-local>` (without using Docker)
+- Generally we prefer that features and bug fixes are submitted as pull requests on their own branch (as described in the  `git-flow workflow <http://danielkummer.github.io/git-flow-cheatsheet/>`_). Submitting against `develop` (but not `master`) is fine for small fixes and changes.
 - We use Django's testing tools — it would be great if new features came with unit tests
-- TODO: more detail on tests and pull request checklist/guidelines
 
 Style guide
 ===========

Dockerfile

@@ -0,0 +1,26 @@
+# Docker file lists all the commands needed to setup a fresh linux instance to
+# run the application specified. docker-compose does not use this.
+
+# Grab a python image
+FROM python:3.6
+
+# Just needed for all things python (note this is setting an env variable)
+ENV PYTHONUNBUFFERED 1
+
+# Setup Node/NPM
+RUN apt-get update && apt-get install curl
+RUN curl -sL https://deb.nodesource.com/setup_6.x | bash && apt-get install -y nodejs
+
+# Copy all our files into the baseimage and cd to that directory
+RUN mkdir /tcd
+WORKDIR /tcd
+# Can this be skipped? Takes ages
+ADD . /tcd/
+
+# Install our node/python requirements
+RUN pip install -r ./requirements_common.txt
+RUN npm install
+
+# Compile all the static files
+RUN npm rebuild node-sass
+RUN python ./tabbycat/manage.py collectstatic --no-input

bin/.gitattributes

@@ -0,0 +1,7 @@
+# Declare files that will always have LF line endings on checkout.
+
+# The docker wait/run commands need this for Windows compatibility
+# Error is ": No such file or directory/usr/bin/env: bash"
+# See: https://github.com/deviantony/docker-elk/issues/36
+
+docker-*.sh text eol=lf

bin/docker-run.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+#   Shorthand to migrate and runserver in docker
+
+# Move up to where we can run commands
+cd tabbycat
+
+# Migrate (can't do it during build; no db connnection)
+python ./manage.py migrate --no-input
+
+# Run the server
+# python ./manage.py runserver 0.0.0.0:8000
+waitress-serve --threads=12 --host=0.0.0.0 --port=8000 wsgi:application

bin/docker-wait.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+#   Use this script to test if a given TCP host/port are available
+#   From https://github.com/vishnubob/wait-for-it/blob/master/wait-for-it.sh
+
+cmdname=$(basename $0)
+
+echoerr() { if [[ $QUIET -ne 1 ]]; then echo "$@" 1>&2; fi }
+
+usage()
+{
+    cat << USAGE >&2
+Usage:
+    $cmdname host:port [-s] [-t timeout] [-- command args]
+    -h HOST | --host=HOST       Host or IP under test
+    -p PORT | --port=PORT       TCP port under test
+                                Alternatively, you specify the host and port as host:port
+    -s | --strict               Only execute subcommand if the test succeeds
+    -q | --quiet                Don't output any status messages
+    -t TIMEOUT | --timeout=TIMEOUT
+                                Timeout in seconds, zero for no timeout
+    -- COMMAND ARGS             Execute command with args after the test finishes
+USAGE
+    exit 1
+}
+wait_for()
+{
+    if [[ $TIMEOUT -gt 0 ]]; then
+        echoerr "$cmdname: waiting $TIMEOUT seconds for $HOST:$PORT"
+    else
+        echoerr "$cmdname: waiting for $HOST:$PORT without a timeout"
+    fi
+    start_ts=$(date +%s)
+    while :
+    do
+        (echo > /dev/tcp/$HOST/$PORT) >/dev/null 2>&1
+        result=$?
+        if [[ $result -eq 0 ]]; then
+            end_ts=$(date +%s)
+            echoerr "$cmdname: $HOST:$PORT is available after $((end_ts - start_ts)) seconds"
+            break
+        fi
+        sleep 1
+    done
+    return $result
+}
+wait_for_wrapper()
+{
+    # In order to support SIGINT during timeout: http://unix.stackexchange.com/a/57692
+    if [[ $QUIET -eq 1 ]]; then
+        timeout $TIMEOUT $0 --quiet --child --host=$HOST --port=$PORT --timeout=$TIMEOUT &
+    else
+        timeout $TIMEOUT $0 --child --host=$HOST --port=$PORT --timeout=$TIMEOUT &
+    fi
+    PID=$!
+    trap "kill -INT -$PID" INT
+    wait $PID
+    RESULT=$?
+    if [[ $RESULT -ne 0 ]]; then
+        echoerr "$cmdname: timeout occurred after waiting $TIMEOUT seconds for $HOST:$PORT"
+    fi
+    return $RESULT
+}
+# process arguments
+while [[ $# -gt 0 ]]
+do
+    case "$1" in
+        *:* )
+        hostport=(${1//:/ })
+        HOST=${hostport[0]}
+        PORT=${hostport[1]}
+        shift 1
+        ;;
+        --child)
+        CHILD=1
+        shift 1
+        ;;
+        -q | --quiet)
+        QUIET=1
+        shift 1
+        ;;
+        -s | --strict)
+        STRICT=1
+        shift 1
+        ;;
+        -h)
+        HOST="$2"
+        if [[ $HOST == "" ]]; then break; fi
+        shift 2
+        ;;
+        --host=*)
+        HOST="${1#*=}"
+        shift 1
+        ;;
+        -p)
+        PORT="$2"
+        if [[ $PORT == "" ]]; then break; fi
+        shift 2
+        ;;
+        --port=*)
+        PORT="${1#*=}"
+        shift 1
+        ;;
+        -t)
+        TIMEOUT="$2"
+        if [[ $TIMEOUT == "" ]]; then break; fi
+        shift 2
+        ;;
+        --timeout=*)
+        TIMEOUT="${1#*=}"
+        shift 1
+        ;;
+        --)
+        shift
+        CLI="$@"
+        break
+        ;;
+        --help)
+        usage
+        ;;
+        *)
+        echoerr "Unknown argument: $1"
+        usage
+        ;;
+    esac
+done
+if [[ "$HOST" == "" || "$PORT" == "" ]]; then
+    echoerr "Error: you need to provide a host and port to test."
+    usage
+fi
+TIMEOUT=${TIMEOUT:-15}
+STRICT=${STRICT:-0}
+CHILD=${CHILD:-0}
+QUIET=${QUIET:-0}
+if [[ $CHILD -gt 0 ]]; then
+    wait_for
+    RESULT=$?
+    exit $RESULT
+else
+    if [[ $TIMEOUT -gt 0 ]]; then
+        wait_for_wrapper
+        RESULT=$?
+    else
+        wait_for
+        RESULT=$?
+    fi
+fi
+if [[ $CLI != "" ]]; then
+    if [[ $RESULT -ne 0 && $STRICT -eq 1 ]]; then
+        echoerr "$cmdname: strict mode, refusing to execute subprocess"
+        exit $RESULT
+    fi
+    exec $CLI
+else
+    exit $RESULT
+fi

bin/osx_docker_start.command

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+#   Front-end to starting docker for OSX
+
+# Get directory this is being run from
+DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
+
+# Go there then go up
+cd "${DIR}"
+cd ..
+
+# Do docker stuff
+docker-compose up
+
+# Open the URL
+open http://0.0.0.0:8000

bin/windows_docker_start.bat

@@ -0,0 +1,15 @@
+:: Move up to main directory
+cd ..
+
+:: Translates from Windows-style to Unix-style paths in volume definitions
+:: https://docs.docker.com/compose/reference/envvars/
+SET COMPOSE_CONVERT_WINDOWS_PATHS=1
+
+:: Run docker
+docker-compose up
+
+:: Open the webiste
+start "" http://localhost:8000
+
+:: Don't just vanish after doing it
+cmd /k

docker-compose.yml

@@ -0,0 +1,41 @@
+# Docker-compose is a way to run multiple containers at once and connect them
+# This sets up and runs postgres and the django dev server as services
+# Reference: https://docs.docker.com/compose/compose-file/
+
+# Initial setup with
+# $ docker-compose up
+
+# Can run management commands with
+# $ docker-compose run web /code/manage.py whatever
+
+
+version: '2'
+services:
+  db:
+    image: postgres:9.6
+    environment:
+      - POSTGRES_PASSWORD=tabbycat
+      - POSTGRES_USER=tabbycat
+      - POSTGRES_DB=tabbycat
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+  web:
+    build: .
+    # Hack to wait until Postgres is up before running things
+    command: ["./bin/docker-wait.sh", "db:5432", "--", "./bin/docker-run.sh"]
+    depends_on:
+      - db
+    expose:
+      - "8000"
+    environment:
+      - DEBUG=1
+      - IN_DOCKER=1
+    image: django
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/tcd
+      - node_modules:/tcd/node_modules
+volumes:
+  pgdata:
+  node_modules:

docs/index.rst

@@ -15,6 +15,7 @@ supporting many custom variations of the above formats too.
 
    install/heroku
    install/local
+   install/docker
    install/linux
    install/osx
    install/windows

docs/install/docker.rst

@@ -0,0 +1,46 @@
+.. _install-docker:
+
+===============================
+Installing Locally using Docker
+===============================
+
+Docker is an application that makes it very easy to load and run a specific collection of software. It allows us to bundle everything necessary to run Tabbycat into a single 'virtual machine' rather than have users install everything needed step-by-step. Once setup Docker will allow you to start and stop a webserver (that in turn runs Tabbycat) whenever you need.
+
+1. Install Docker
+=================
+
+Docker offers a standard installer for Windows and OS X. Go to the relevant page linked below, download the *Stable Channel* build, then open the file and follow the install prompts.
+
+- `Docker for Mac download page <https://docs.docker.com/docker-for-mac/>`_.
+- `Docker for Windows download page <https://docs.docker.com/docker-for-windows/>`_.
+
+  .. note:: Docker requires Windows 10. Before or shortly after installing
+    Docker will ask you to enable hypervisor and restart your PC. You must do this step.
+
+- If you run Linux `follow the instructions for your particular release here <https://docs.docker.com/engine/installation/linux/>`_.
+
+2. Download Tabbycat
+====================
+
+1. `Go to the page for our latest release <https://github.com/czlee/tabbycat/releases/latest>`_.
+
+2. Download the zip or tar.gz file.
+
+3. Extract all files in it to a folder of your choice.
+
+3. Run Tabbycat in Docker
+=========================
+
+1. Ensure that Docker application is open (there should be a whale icon in your menu/task bar) and that it says that Docker is running.
+
+2. Browse to the location where you extracted Tabbycat to and then open up the **bin** folder there. Within that folder:
+
+    - If on OSX, open **osx_docker_start.command**
+    - If on Windows, open **windows_docker_start.bat**
+    - If on Linux, open up a terminal in the Tabbycat folder (ie the folder containing ``README.md``) and run ``$ docker-compose up``
+
+3. A terminal window should popup and bunch of text scroll by. If this is your first time running Docker it may take up to half an hour to download and setup the virtul machine.
+
+4. Once the new text has stopped scrolling for a little while it should automatically open up the Tabbycat site in your default browser. If this doesn't happen navigation to http://localhost:8000/ (On Windows) or http://0.0.0.0:8000 (On OSX/Linux) yourself.
+
+  .. note:: If you want to reopen Tabbycat at a later time (say after restarting) repeat steps 1 through 3 under 'Run Tabbycat in Docker'.