diff --git a/Dockerfile b/Dockerfile
index 35ce029..cb40c91 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,3 +4,7 @@ WORKDIR /app
 COPY . /app
 
 RUN pip install --upgrade --no-cache-dir -r requirements.txt
+
+ENV PYTHONPATH=.
+
+CMD ["python", "scripts/manage.py", "runserver", "-t 0.0.0.0", "-p 5000"]
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..2834887
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,19 @@
+docker:
+	@docker build -t mozilla/onyx . 
+
+run:
+	@docker run -d -p 5000:5000 --name onyx mozilla/onyx
+
+start:
+	@docker start onyx
+
+stop:
+	@docker stop onyx
+
+log:
+	@docker logs -f onyx
+
+clean:
+	@docker rm -f onyx
+
+.PHONY: docker run start stop log clean
diff --git a/README.md b/README.md
index 8b8533e..9a425ca 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,48 @@
-# onyx
+# Onyx
 
-[![Build Status](https://travis-ci.org/oyiptong/onyx.svg?branch=master)](https://travis-ci.org/oyiptong/onyx)
+[![Build Status](https://travis-ci.org/mozilla/onyx.svg?branch=master)](https://travis-ci.org/mozilla/onyx)
 [![Coverage Status](https://coveralls.io/repos/oyiptong/onyx/badge.png?branch=master)](https://coveralls.io/r/oyiptong/onyx?branch=master)
 
 Link server and engagement metrics aggregator for Firefox Directory Links
 
+# Install
+```sh
+# install Onyx in a local Python virtualenv
+$ ./setup-project.sh
+
+# run the dev server at localhost:5000
+$ manage.py runserver
+
+# ping the server
+$ curl -v localhost:5000/__heartbeat__
+```
+
+# Run within docker
+
+You can run Onyx within docker (Note: *NOT* for production).
+
+```sh
+# build the Onyx docker image locally
+$ make docker
+
+# run the container at localhost:5000
+$ make run
+
+# tail the logs
+$ make log
+
+# stop the container
+$ make stop
+
+# start the stopped container
+$ make start
+
+# remove the container
+$ make clean
+```
+
+# Links
+
 There are a few API endpoints we care about:
 
 * [/v2/links/fetch/`locale`](#v2linksfetchlocale)