diff --git a/docker/.dockerignore b/docker/.dockerignore
new file mode 100644
index 00000000000..79ba0996010
--- /dev/null
+++ b/docker/.dockerignore
@@ -0,0 +1,5 @@
+*
+!Gemfile
+!Gemfile.lock
+!db/functions
+!db/docker_postgres.sh
diff --git a/docker/DOCKER.md b/docker/DOCKER.md
new file mode 100644
index 00000000000..5e8be10540a
--- /dev/null
+++ b/docker/DOCKER.md
@@ -0,0 +1,99 @@
+# Using Docker to run OpenStreetMap
+
+Using [Docker](https://www.docker.com/) will allow you to install the OpenStreetMap application and all its' dependencies in a container, almost with a single command.
+
+These instructions gloss over the precise details of the dependencies and their configuration but these can be found in full detail at [INSTALL.md](INSTALL.md).
+
+The first step is to fork/clone the repo to your local machine. The repository is reasonably large (~150MB) and it's unlikely that you need the full history. If you are happy to wait for it all to download, run:
+```
+git clone https://github.com/openstreetmap/openstreetmap-website.git
+```
+
+To clone only the most recent version (~23MB), instead use a 'shallow clone':
+
+```
+git clone --depth=1 https://github.com/openstreetmap/openstreetmap-website.git
+```
+
+Now change working directory to the `openstreetmap-website`:
+
+```
+cd openstreetmap-website
+```
+
+### Storage setup
+
+```
+cp config/example.storage.yml config/storage.yml
+```
+
+### Database
+
+```
+cp config/example.database.yml config/database.yml
+```
+
+Set `username` to postgres and `host` to db leave the `password` blank
+
+
+### App configuration
+
+```
+cp config/settings.yml config/settings.local.yml
+```
+
+### Installation
+
+In the root directory run:
+
+```
+docker-compose -f docker/docker-compose.yml up
+```
+Now if this is your first time running or you have removed cache this will take some time to complete. So grab tea/coffee and seat tight. Upon successfull build it should show
+
+### Migrations
+While `docker-compose up` is running, open another terminal windows and run:
+
+```
+docker-compose -f docker/docker-compose.yml exec web bundle exec rake db:migrate
+```
+
+### Node.js modules
+We use Yarn to manage the Node.js modules required for the project.:
+
+```
+docker-compose -f docker/docker-compose.yml exec web bundle exec rake yarn:install
+```
+
+Once these are complete you should be able to visit the app at http://localhost:3000
+
+If localhost does not work, you can use the IP address of the docker-machine.
+
+### Tests
+
+```
+docker-compose -f docker/docker-compose.yml exec web bundle exec rake test:db
+```
+
+### Bash
+
+If you want to get onto the web container and run specific commands you can fire up bash via:
+
+```
+docker-compose -f docker/docker-compose.yml exec web /bin/bash
+```
+
+Similarly, if you want to get onto the db container use:
+
+```
+docker-compose -f docker/docker-compose.yml exec db /bin/bash
+```
+
+### Populating the database
+This  installation comes with no geographic data loaded. You can either create new data using one of the editors (Potlatch 2, iD, JOSM etc) or by loading an OSM extract.
+
+After installing but before creating any users or data, import an extract with [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and the `--write-apidb` task. The `web` container comes with `osmosis` pre-installed. So to populate data with a `.osm.pbf` use the following command:
+
+```
+docker-compose -f docker/docker-compose.yml exec web osmosis --read-pbf /path/to/file.osm.pbf --write-apidb host="db" database="openstreetmap" user="postgres"  validateSchemaVersion="no"
+```
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 00000000000..d176cbb2cfe
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,30 @@
+FROM ruby:2.5-slim
+
+# install packages
+# fixes dpkg man page softlink error while installing postgresql-client [source: https://stackoverflow.com/a/52655008/5350059]
+RUN mkdir -p /usr/share/man/man1 && mkdir -p /usr/share/man/man7
+RUN apt-get update && apt-get install curl -y
+RUN apt-get clean && rm -rf /var/lib/apt/lists/*
+
+
+#npm is not available in Debian repo so following official instruction [source: https://github.com/nodesource/distributions/blob/master/README.md#debinstall]
+RUN curl -sL https://deb.nodesource.com/setup_10.x -o nodesource_setup.sh && bash nodesource_setup.sh && rm nodesource_setup.sh
+RUN apt-get install -y --no-install-recommends ruby-dev libarchive-dev libmagickwand-dev libxml2-dev libxslt1-dev build-essential libpq-dev libsasl2-dev imagemagick libffi-dev locales postgresql-client nodejs osmosis
+RUN apt-get clean && rm -rf /var/lib/apt/lists/*
+RUN npm install yarn phantomjs-prebuilt -g --unsafe-perm
+
+
+# Setup app location
+RUN mkdir -p /app
+WORKDIR /app
+
+# Install gems
+ADD Gemfile* /app/
+RUN bundle install
+# Setup local
+RUN sed -i -e 's/# en_GB.UTF-8 UTF-8/en_GB.UTF-8 UTF-8/' /etc/locale.gen && \
+    echo 'LANG="en_GB.UTF-8"'>/etc/default/locale && \
+    dpkg-reconfigure --frontend=noninteractive locales && \
+    update-locale LANG=en_GB.UTF-8
+
+ENV LANG en_GB.UTF-8
diff --git a/docker/Dockerfile.postgres b/docker/Dockerfile.postgres
new file mode 100644
index 00000000000..f1c75c15c4d
--- /dev/null
+++ b/docker/Dockerfile.postgres
@@ -0,0 +1,26 @@
+FROM postgres:11
+
+ADD docker/docker_postgres.sh docker-entrypoint-initdb.d/docker_postgres.sh
+
+# compiling ruby from source as official debian has ruby 2.3 and we need => 2.4
+RUN apt-get update
+RUN apt-get install -y curl build-essential libreadline-dev libssl-dev libcurl4-openssl-dev postgresql-server-dev-all zlib1g-dev libxml2-dev
+RUN curl -L https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.4.tar.gz | tar zx
+RUN cd ruby-2.6.4 && ./configure && make && make install
+RUN cd ..  && rm -r ruby-2.6.4
+RUN apt-get clean && rm -rf /var/lib/apt/lists/*
+
+
+# Setup app location
+RUN mkdir -p /app
+WORKDIR /app
+
+# add database functions directory
+ADD db/functions/ /app/db/functions/
+
+# Install gems
+ADD Gemfile* /app/
+RUN bundle install
+
+# change ownership to postgres as while running docker_postgres.sh postgres will need write access
+RUN chown -R postgres /app/db
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
new file mode 100644
index 00000000000..39a4166e89b
--- /dev/null
+++ b/docker/docker-compose.yml
@@ -0,0 +1,25 @@
+version: '2'
+services:
+  web:
+    image: openstreetmap-website:v1
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+    volumes:
+      - ..:/app
+    ports:
+      - "3000:3000"
+    command: bundle exec rails s -p 3000 -b '0.0.0.0'
+    depends_on:
+      - db
+    environment:
+      DATABASE_URL: postgres://postgres@db:5432
+  db:
+    image: openstreetmap-db:v1
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.postgres
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_DB: openstreetmap
diff --git a/docker/docker_postgres.sh b/docker/docker_postgres.sh
new file mode 100644
index 00000000000..8f0fa295faf
--- /dev/null
+++ b/docker/docker_postgres.sh
@@ -0,0 +1,7 @@
+#!/bin/bash
+set -e
+psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -c "CREATE EXTENSION btree_gist" openstreetmap
+make -C db/functions libpgosm.so
+psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -c "CREATE FUNCTION maptile_for_point(int8, int8, int4) RETURNS int4 AS '/app/db/functions/libpgosm', 'maptile_for_point' LANGUAGE C STRICT" openstreetmap
+psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -c "CREATE FUNCTION tile_for_point(int4, int4) RETURNS int8 AS '/app/db/functions/libpgosm', 'tile_for_point' LANGUAGE C STRICT" openstreetmap
+psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -c "CREATE FUNCTION xid_to_int4(xid) RETURNS int4 AS '/app/db/functions/libpgosm', 'xid_to_int4' LANGUAGE C STRICT" openstreetmap