diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..691e6d08782ec14016d6b546ae1afcd5ef23adea
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# Crowd
+
+Docker image to run [Atlassian Crowd](https://www.atlassian.com/software/crowd).
+
+## Building
+
+```
+docker build --rm -t registry.codemate.se/crowd .
+```
+
+## Usage
+
+It's as simple as:
+
+```
+docker pull registry.codemate.se/crowd
+docker run -d registry.codemate.se/crowd
+```
+
+### Customize exposed port
+
+By default, the port `8095` (web interface) is mapped to a random port on the docker host. To customize, run:
+
+```
+docker run -p 8095:8095 -d registry.codemate.se/crowd
+```
+
+More info about port redirection can be found in the official Docker [documentation](http://docs.docker.io/en/latest/use/port_redirection/).
+
+### Persist application data on the docker host
+
+By default the application data is stored in the container in `/home/crowd`. You can map a directory on the host to this directory to store the application data outside of the container.
+
+This is useful if you want to start containers using different versions of the image but with the same application data (including license) or if you want to backup this directory on the host. It also allows you to upgrade your server without losing your data:
+
+```
+docker run -v /data/crowd:/home/crowd -d registry.codemate.se/crowd
+```
+
+### Running a different Crowd version
+
+By default, the container downloads and installs Crowd v2.7.2 on the first boot. To specify which version to install, set the environment variable `CROWD_VERSION`:
+
+```
+docker run -e CROWD_VERSION=2.7.2 -d registry.codemate.se/crowd
+```
+
+### Overriding Crowd files
+
+By providing an environment variable name `CROWD_OVERLAY` that points to a gzipped tar file you can apply an overlay on the Crowd installation. This tarball will be unzipped and extracted in the root of the Crowd installation directory. The overlay enables you to add custom crowd configurations such as SSL or Crowd integration.
+
+```
+docker run -e CROWD_OVERLAY=http://10.0.0.1/crowd-config.tgz -d registry.codemate.se/crowd
+```
+
+The overlay is fetched using curl so if you need to provide basic auth credentials simply prefix the url with the credentials, for example:
+
+```
+CROWD_OVERLAY="-u username:password http://10.0.0.1/crowd-config.tgz"
+```
+
+### Initializing MySQL
+
+By providing an environment variable name `MYSQL_INIT` that points to an SQL script you initialize the MySQL database.
+
+```
+docker run -e MYSQL_INIT=http://10.0.0.1/crowd-init.sql -d registry.codemate.se/crowd
+```
+
+Basic auth credentials can be used as mentioned in the Crowd overlay section.
+
+### Combined options
+
+The following example shows the options we use for our CI environment:
+
+```
+docker run \
+  --name crowd \
+  -e JAVA_OPTS=-Xmx1024m \
+  -e CROWD_VERSION=2.7.2 \
+  -e CROWD_OVERLAY=http://10.0.0.1/crowd-config.tgz \
+  -v /opt/application-data/crowd:/home/crowd \
+  -p 8095:8095 \
+  -p 8096:8096 \
+  -d registry.codemate.se/crowd
+```
+
+## Directories
+
+* `/opt/atlassian-crowd-$CROWD_VERSION` - Crowd installation directory
+* `/home/crowd` - Crowd home directory (`CROWD_HOME`)
+
+## Variables
+
+* `CROWD_HOME` - Crowd home directory (default `/home/crowd`)
+* `CROWD_VERSION` - The version to install an run (default `2.7.2`)
+* `CROWD_OVERLAY` - A URL pointing to an tarball overlay
+* `MYSQL_INIT` - A URL pointing to an SQL script
+
+## Exposed ports
+
+* `25` - Exim SMTP
+* `3306` - MySQL
+* `8095` - Crowd web interface
+* `8096` - Crowd web interface (extra)