[Reviewer: Matt] Add note about upgrading from 3.13.0-74-generic

README.md

@@ -2,26 +2,39 @@
 
 This repository contains [Dockerfiles](https://docs.docker.com/reference/builder/) for use with [Docker](https://www.docker.com/) and [Compose](https://docs.docker.com/compose/) to deploy [Project Clearwater](http://www.projectclearwater.org).
 
+There are two options for installing Docker:
+
+- using Docker Compose, which sets up appropriate connections between Docker containers. This is the recommended approach.
+- manually, if Docker Compose isn't available. In this case you need to use some Docker options to set up the networking config that Compose would set up automatically.
+
+You should follow the "Common Preparation" section, then either the "Using Compose" or the "Manual Turn-Up" section.
+
+## Common Preparation
+
+When using the `3.13.0-74-generic` kernel, we've seen [an issue](https://github.com/Metaswitch/clearwater-docker/issues/24) which causes Clearwater not to start properly. If you are using this kernel (`uname -r` will tell you), you should install a newer kernel (e.g. with `sudo apt-get install linux-image-3.13.0-87-generic`) and reboot.
+
+To prepare your system to deploy Clearwater on Docker, run:
+
+    # Install Docker (on Ubuntu).
+    wget -qO- https://get.docker.com/ | sh
+
+    # Checkout clearwater-docker.
+    git clone --recursive git@github.com:Metaswitch/clearwater-docker.git
+
 ## Using Compose
 
 There is a [Compose file](minimal-distributed.yaml) to instantiate a minimal (non-fault-tolerant) distributed Clearwater deployment under Docker.
 
 ### Preparation
 
-To prepare your system to deploy Clearwater using compose, run:
-
-    # Install Docker (on Ubuntu) - we need the latest for compatibility with Compose.
-    wget -qO- https://get.docker.com/ | sh
+To prepare your system to deploy Clearwater using Compose, after running the common preparation steps above, run:
 
     # Install Docker Compose (on Ubuntu).
     sudo apt-get install python-pip -y
     sudo pip install -U docker-compose
 
-    # Checkout clearwater-docker.
-    git clone --recursive git@github.com:Metaswitch/clearwater-docker.git
-    cd clearwater-docker
-
     # Build the base Clearwater docker image.
+    cd clearwater-docker
     sudo docker build -t clearwater/base base
 
 ### Starting Clearwater
@@ -43,16 +56,10 @@ If you can't or don't want to use Compose, you can turn the deployment up manual
 
 ### Preparation
 
-To prepare your system to deploy Clearwater manually, run:
-
-    # Install Docker (on Ubuntu).
-    wget -qO- https://get.docker.com/ | sh
-
-    # Checkout clearwater-docker.
-    git clone --recursive git@github.com:Metaswitch/clearwater-docker.git
-    cd clearwater-docker
+To prepare your system to deploy Clearwater without using Compose, after running the common preparation steps above, run:
 
     # Build the Clearwater docker images.
+    cd clearwater-docker
     for i in base bono ellis homer homestead ralf sprout ; do sudo docker build -t clearwater/$i $i ; done
 
 ### Starting Clearwater