Document how to generate local dev tiles

.dockerignore

@@ -2,6 +2,7 @@
 **/__pycache__
 *.sublime-project
 *.sublime-workspace
+*.awscreds
 venv
 
 .circleci

.gitignore

@@ -2,6 +2,7 @@
 *.py[co]
 *.so
 *.sublime-*
+*.awscreds
 .DS_Store
 docs/_build/
 ichnaea/content/static/datamap/csv/

Makefile

@@ -46,6 +46,7 @@ default:
 	@echo "  clean-assets     - remove generated static assets"
 	@echo "  update-vendored  - re-download vendor source and test data"
 	@echo "  update-reqs      - regenerate Python requirements"
+	@echo "  local-map        - generate local map tiles"
 	@echo ""
 	@echo "  help             - see this text"
 	@echo ""
@@ -141,3 +142,7 @@ update-vendored: my.env
 .PHONY: update-reqs
 update-reqs: my.env
 	${DC} run --rm --no-deps app shell ./docker/run_update_requirements.sh
+
+.PHONY: local-map
+local-map: my.env .docker-build
+	${DC} run --rm app shell ./docker/run_local_map.sh

docs/configure.rst

@@ -88,6 +88,7 @@ documentation <metrics>`.
 
 All metrics are prefixed with a `location` namespace.
 
+.. _map_tile_and_download_assets:
 
 Map tile and download assets
 ----------------------------
@@ -100,12 +101,21 @@ available via a HTTPS frontend (Amazon CloudFront).
 
 Set ``ASSET_BUCKET`` and ``ASSET_URL`` accordingly.
 
+To access the ``ASSET_BUCKET``, authorized AWS credentials are needed inside
+the Docker image. See the `Boto3 credentials documentation`_ for details.
+
+.. _`Boto3 credentials documentation`: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
+
+The development environment defaults to serving map tiles from the web server,
+and not serving public export files for download.
+
+.. _mapbox:
 
 Mapbox
 ------
 
-The web site content uses Mapbox to generate tiles. In order to do this,
+The web site content uses Mapbox to display a world map. In order to do this,
-it requires a Mapbox API token.
+it requires a Mapbox API token. Without a token, the map is not displayed.
 
 You can create an account on their site: https://www.mapbox.com
 

docs/local_dev.rst

@@ -271,3 +271,36 @@ source. Update ``docker.make`` for the desired versions, and run::
     $ make update-vendored build test
 
 Commit the updated source tarballs.
+
+Building Datamap Tiles
+======================
+
+To build datamap tiles for the local development environment, run::
+
+    $ make local-map
+
+If you have data in the ``datamap`` tables, this will create many files
+under ``ichnaea/content/static/datamap``. This uses
+``ichnaea/scripts/datamap.py``, which can also be run directly.
+
+To see the map locally, you will need to configure :ref:`mapbox`. A free
+developer account should be sufficient.
+
+To use an S3 bucket for tiles, you'll need to set ``ASSET_BUCKET`` and
+``ASSET_URL`` (see :ref:`map_tile_and_download_assets`).
+To upload tiles to an S3 bucket, you'll also need AWS credentials that
+can read, write, and delete objects in the ``ASSET_BUCKET``. Here are
+two ways, neither of which is ideal since it adds your AWS credentials
+in plain text:
+
+1. Add credentials as environment variables ``AWS_ACCESS_KEY_ID`` and
+   ``AWS_SECRET_ACCESS_KEY`` in ``my.env``.
+2. Add credentials to a file ``my.awscreds`` in the project folder,
+   and add ``AWS_SHARED_CREDENTIALS_FILE=/app/my.awscreds`` to ``my.env``.
+
+You can then generate and upload tiles with::
+
+    $ docker-compose run --rm app map
+
+This will generate a fresh set of tiles in a temporary directory and
+sync the S3 bucket with the changes.