<p><b>@gravitystorm</b> requested changes on this pull request.</p>

<p>Overall looks great to me! Just a few changes required to bring this into line with INSTALL.md</p>
<p>Talking of which, there should be a paragraph added to the top of INSTALL.md to describe that you can use Docker to set up your development environment, just like you can with Vagrant.</p><hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340513067">Dockerfile</a>:</p>
<pre style='color:#555'>> @@ -0,0 +1,52 @@
+FROM ruby:2.5
+
+# 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
+
+# npm is not available in Debian repo so following official instruction [source: https://github.com/nodesource/distributions/blob/master/README.md#debinstall]
</pre>
<p>I have more knowledge of Ubuntu than Debian, but as far as I can tell:</p>
<ul>
<li>ruby:2.5 is an alias for ruby:2.5-buster (<a href="https://hub.docker.com/_/ruby/" rel="nofollow">https://hub.docker.com/_/ruby/</a>)</li>
<li>buster contains npm (<a href="https://packages.debian.org/buster/npm" rel="nofollow">https://packages.debian.org/buster/npm</a>)</li>
<li>but we don't need npm anyway, only <code>nodejs</code> and <code>yarn</code></li>
</ul>

<hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340514333">Dockerfile</a>:</p>
<pre style='color:#555'>> +      libmagickwand-dev \
+      libpq-dev \
+      libsasl2-dev \
+      libxml2-dev \
+      libxslt1-dev \
+      locales \
+      nodejs \
+      osmosis \
+      postgresql-client \
+      ruby-dev && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# install npm packages
+RUN npm install -g --unsafe-perm \
+      phantomjs-prebuilt \
</pre>
<p><a href="https://packages.debian.org/buster/phantomjs" rel="nofollow">Debian buster comes with a phantomjs package</a>. Should we just install that instead?</p>

<hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340515562">Dockerfile</a>:</p>
<pre style='color:#555'>> +      libpq-dev \
+      libsasl2-dev \
+      libxml2-dev \
+      libxslt1-dev \
+      locales \
+      nodejs \
+      osmosis \
+      postgresql-client \
+      ruby-dev && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# install npm packages
+RUN npm install -g --unsafe-perm \
+      phantomjs-prebuilt \
+      yarn
</pre>
<p>I find using npm to install yarn a bit of a roundabout way to go. Could we <a href="https://yarnpkg.com/en/docs/install#debian-stable" rel="nofollow">install the yarn package using the yarn repository</a> instead?</p>

<hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340518798">DOCKER.md</a>:</p>
<pre style='color:#555'>> +    docker-compose run --rm web osmosis \
+        -verbose    \
+        --read-pbf district-of-columbia-latest.osm.pbf \
+        --write-apidb \
+            host="db" \
+            database="openstreetmap" \
+            user="openstreetmap" \
+            validateSchemaVersion="no"
+
+Once you have data loaded for Washington, DC you should be able to navigate to `http://localhost:3000/#map=12/38.8938/-77.0146` to begin working with your local instance.
+
+### Additional Configuration
+
+See `CONFIGURE.md` for information on how to manage users and enable OAuth for iD, JOSM etc.
+
+### Tests
</pre>
<p>Running the tests section should come before the loading an extract or additional configuration sections. This is because the goal for the user is to ensure their development environment is set up correctly, as validated by the tests</p>

<hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340520078">DOCKER.md</a>:</p>
<pre style='color:#555'>> @@ -0,0 +1,100 @@
+# Using Docker and Docker Compose to run OpenStreetMap
</pre>
<p>"Using Docker and Docker Compose  to set up The Rails Port for development and testing" - based on the wording in the current INSTALL.md and to make it clear that these docker images are designed for development and testing, not necessarily for production.</p>

<hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340522251">DOCKER.md</a>:</p>
<pre style='color:#555'>> +If this is your first time running or you have removed cache this will take some time to complete. Once the Docker images have finished building you can launch the images as containers.
+
+To launch the app run:
+
+    docker-compose up -d
+
+This will launch one Docker container for each 'service' specified in `docker-compose.yml` and run them in the background. There are two options for inspecting the logs of these running containers:
+
+- You can tail logs of a running container with a command like this: `docker-compose logs -f web` or `docker-compose logs -f db`.
+- Instead of running the containers in the background with the `-d` flag, you can launch the containers in the foreground with `docker-compose up`. The downside of this is that the logs of all the 'services' defined in `docker-compose.yml` will be intermingled. If you don't want this you can mix and match - for example, you can run the database in background with `docker-compose up -d db` and then run the Rails app in the foreground via `docker-compose up web`.
+
+### Migrations
+
+Run the Rails database migrations:
+
+    docker-compose run --rm web rake db:migrate
</pre>
<p>For consistency and reliability, we should have <code>... bundle exec rake db:migrate</code> here</p>

<hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340522365">DOCKER.md</a>:</p>
<pre style='color:#555'>> +        --read-pbf district-of-columbia-latest.osm.pbf \
+        --write-apidb \
+            host="db" \
+            database="openstreetmap" \
+            user="openstreetmap" \
+            validateSchemaVersion="no"
+
+Once you have data loaded for Washington, DC you should be able to navigate to `http://localhost:3000/#map=12/38.8938/-77.0146` to begin working with your local instance.
+
+### Additional Configuration
+
+See `CONFIGURE.md` for information on how to manage users and enable OAuth for iD, JOSM etc.
+
+### Tests
+
+    docker-compose run --rm web rake test:db
</pre>
<p>bundle exec</p>

<hr>

<p>In <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409#discussion_r340523386">Dockerfile</a>:</p>
<pre style='color:#555'>> +
+# 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
</pre>
<p>There needs to be a bit about <code>bundle exec rake yarn:install</code> somewhere, either here in the docker config, or elsewhere in the manual installation notes.</p>

<p style="font-size:small;-webkit-text-size-adjust:none;color:#666;">—<br />You are receiving this because you are subscribed to this thread.<br />Reply to this email directly, <a href="https://github.com/openstreetmap/openstreetmap-website/pull/2409?email_source=notifications&email_token=AAK2OLJ5N3OVLXLMPFTRYY3QRFMA5A5CNFSM4JDURRXKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCJWAGHQ#pullrequestreview-309068574">view it on GitHub</a>, or <a href="https://github.com/notifications/unsubscribe-auth/AAK2OLK6PGKI4VSZBWKGBCTQRFMA5ANCNFSM4JDURRXA">unsubscribe</a>.<img src="https://github.com/notifications/beacon/AAK2OLNSDI3WOMJXSZSKZ2TQRFMA5A5CNFSM4JDURRXKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCJWAGHQ.gif" height="1" width="1" alt="" /></p>
<script type="application/ld+json">[
{
"@context": "http://schema.org",
"@type": "EmailMessage",
"potentialAction": {
"@type": "ViewAction",
"target": "https://github.com/openstreetmap/openstreetmap-website/pull/2409?email_source=notifications\u0026email_token=AAK2OLJ5N3OVLXLMPFTRYY3QRFMA5A5CNFSM4JDURRXKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCJWAGHQ#pullrequestreview-309068574",
"url": "https://github.com/openstreetmap/openstreetmap-website/pull/2409?email_source=notifications\u0026email_token=AAK2OLJ5N3OVLXLMPFTRYY3QRFMA5A5CNFSM4JDURRXKYY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCJWAGHQ#pullrequestreview-309068574",
"name": "View Pull Request"
},
"description": "View this Pull Request on GitHub",
"publisher": {
"@type": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]</script>