PR for issue CrunchyData#63 - Docker enhancements and example (CrunchyData#64)

Add Alpine-based self-built Dockerfile, and examples of data-loading using shp2pgsql and psql within PostGIS Container

Author: justb4

Dockerfile.alpine

@@ -0,0 +1,46 @@
+# Lightweight Alpine-based pg_tileserv Docker Image
+# Author: Just van den Broecke
+FROM golang:1.15.5-alpine3.12
+
+# Build ARGS
+ARG VERSION="latest-alpine-3.12"
+
+RUN mkdir /app
+ADD . /app/
+WORKDIR /app
+RUN go build -v -ldflags "-s -w -X main.programVersion=${VERSION}"
+
+# Multi-stage build: only copy build result and resources
+FROM alpine:3.12
+
+LABEL original_developer="Crunchy Data" \
+    contributor="Just van den Broecke <[email protected]>" \
+    vendor="Crunchy Data" \
+	url="https://crunchydata.com" \
+	release="${VERSION}" \
+	org.opencontainers.image.vendor="Crunchy Data" \
+	os.version="3.12"
+
+RUN apk --no-cache add ca-certificates && mkdir /app
+WORKDIR /app/
+COPY --from=0 /app/pg_tileserv /app/
+COPY --from=0 /app/assets /app/assets
+
+VOLUME ["/config"]
+
+USER 1001
+EXPOSE 7800
+
+ENTRYPOINT ["/app/pg_tileserv"]
+CMD []
+
+# To build and run specific version
+#
+# export VERSION="latest-alpine-3.12"
+# docker build --build-arg VERSION=${VERSION} -t pramsey/pg_tileserv:${VERSION} -f Dockerfile.alpine
+#
+# Best is to use another PostGIS Docker Container whoose host is reachable from the pg_tileserv Container.
+# docker run -dt -e DATABASE_URL=postgres://user:pass@host/dbname -p 7800:7800 pramsey/pg_tileserv:${VERSION}
+#
+# See a full example using Docker Compose under examples/docker
+#

README.md

@@ -39,6 +39,11 @@ SET DATABASE_URL=postgresql://username:password@host/dbname
 pg_tileserv.exe
 ```
 
+### Docker
+
+Use [Dockerfile.alpine](Dockerfile.alpine) to build a lightweight (18MB expanded) Docker Image.
+See also [a full example with Docker Compose](examples/docker/README.md).
+
 ## Trouble-shooting
 
 To get more information about what is going on behind the scenes, run with the `--debug` commandline parameter on, or turn on debugging in the configuration file:

examples/docker/README.md

@@ -0,0 +1,69 @@
+# Docker Examples
+
+by: Just van den Broecke - justb4 (@) gmail.com
+
+This example uses Docker Compose with `pg_tileserv` and PostGIS (v3) Docker Images.
+Run with these steps: Build, Run, Load Vector Data, and run the
+standard web-viewer examples like [Leaflet](../leaflet/leaflet-tiles.html).
+
+We use a [docker-compose.yml file](docker-compose.yml) with environment settings in
+[pg_tileserv.env](pg_tileserv.env) and [pg.env](pg.env) for `pg_tileserv` and the PG database.
+
+## Build
+
+* `docker-compose build`
+
+This should build the latest [Alpine-based Docker Image](../../Dockerfile.alpine) for `pg_tileserv`.
+
+## Run
+
+* `docker-compose up`
+
+NB on the first run the PostGIS Docker Image is downloaded and the DB initialized. `pg_tileserv` may not be able to connect.
+In that case stop the Docker Compose process (ctrl-C) and run again. In another terminal window test
+if `pg_tileserv` Container is at least running:
+
+* `curl -v http://localhost:7800/public.ne_50m_admin_0_countries/2/2/3.pbf`.
+
+You will see an regular error message like *"Unable to get layer 'public.ne_50m_admin_0_countries"* as no data is yet in the database.
+
+## Load Data
+
+We load all sample data using `shp2pgsql` and `psql` within the PostGIS Docker Container, so we don't need to install any Postgres/PostGIS tools locally.
+The `./data` dir is mapped into the Docker Container at `/work`.
+
+First Download these files into the `./data` subdir:
+
+* Natural Earth [Admin 0 Countries](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/).
+* [fire hydrant data](https://opendata.vancouver.ca/explore/dataset/water-hydrants/download/?format=shp&timezone=America/Los_Angeles&lang=en&epsg=26910)"
+
+Unzip these two zip-files within the `./data` subdir.
+
+To run also the [OpenLayers Voronoi example](../openlayers/openlayers-function-click.md) using Docker, we apply
+the [OpenLayers Function-click SQL](../openlayers/openlayers-function-click.sql). This example demonstrates the powerful "Function" capability of `pg_tileserv`,
+creating the `public.hydrants_delaunay()` function in your database.
+
+To load the two datasets and Function SQL, use the [load-data.sh helper script](load-data.sh)
+
+* `./load-data.sh`
+* restart the docker-compose stack
+
+The above data-loading script `exec`s the running PostGIS Docker Container `pg_tileserv_db` as for example:
+
+* `docker-compose exec pg_tileserv_db sh -c "shp2pgsql -d -D -s 4326 /work/ne_50m_admin_0_countries.shp | psql -U tileserv -d tileserv"`
+
+## Run Webviewers
+
+As the `pg_tileserv` container has a Docker port-mapping to localhost:7800, you can use the standard HTML examples locally in your browser.
+In a real-world application you would run these in a web-server container like `nginx` or `Apache httpd`.
+
+See [Leaflet](../leaflet/leaflet-tiles.html), [MapBox](../mapbox-gl-js/mapbox-gl-js-tiles.html) and [OpenLayers](../openlayers/openlayers-tiles.html).
+And the  [openlayers-function-click.html](../openlayers/openlayers-function-click.html) for the Voronoi Function example.
+
+## Clean/Restart
+
+If something goes wrong along the way, or you want a clean restart, run this script:
+
+* `./cleanup.sh`
+
+This will delete dangling Docker Containers and and Images and the DB volume

examples/docker/cleanup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# General cleanup, first stop
+
+# first make sure the compose stack is stopped
+docker-compose stop
+
+#
+# Remove all exited containers
+for c in $(docker ps -a -f status=exited -q)
+do
+	docker rm ${c}
+done
+
+# And dangling images
+for i in $(docker images -f dangling=true -q)
+do
+	docker rmi ${i}
+done
+
+# Remove the DB Volume, removes database
+docker volume rm docker_pg_tileserv_db

examples/docker/data/.gitignore

@@ -0,0 +1,8 @@
+*.zip
+*.cpg
+*.dbf
+*.prj
+*.html
+*.shp
+*.shx
+*.txt

examples/docker/data/.gitkeep

@@ -0,0 +1,40 @@
+# pg-tileserv Docker Compose example setup.
+#
+# To build/run, see README.md
+#
+version: "3"
+
+services:
+  pg_tileserv:
+    image: pramsey/pg_tileserv:latest-alpine-3.12
+    build:
+      context: ../..
+      dockerfile: Dockerfile.alpine
+      args:
+        VERSION: latest-alpine-3.12
+
+    container_name: pg_tileserv
+
+    env_file:
+      - pg_tileserv.env
+
+    depends_on:
+      - pg_tileserv_db
+
+    ports:
+      - 7800:7800
+
+  pg_tileserv_db:
+    image: postgis/postgis:13-3.0-alpine
+
+    container_name: pg_tileserv_db
+
+    volumes:
+      - ./data:/work
+      - pg_tileserv_db:/var/lib/postgresql/data
+
+    env_file:
+      - pg.env
+
+volumes:
+  pg_tileserv_db:

examples/docker/docker-compose.yml

@@ -0,0 +1,14 @@
+# Shortcuts to load all data in PostGIS DB in Docker Container
+# NB the docker-compose stack must be running !
+#
+
+# Load Admin 0 countries
+docker-compose exec pg_tileserv_db sh -c "shp2pgsql -D -s 4326 /work/ne_50m_admin_0_countries.shp | psql -U tileserv -d tileserv"
+
+# Load Vancouver Water Hydrants
+docker-compose exec pg_tileserv_db sh -c "shp2pgsql -D -s 26910 -I /work/water-hydrants.shp hydrants | psql -U tileserv -d tileserv"
+
+# Load SQL Functions for OpenLayers example
+cp ../openlayers/openlayers-function-click.sql ./data/
+docker-compose exec pg_tileserv_db sh -c "cat /work/openlayers-function-click.sql | psql -U tileserv -d tileserv"
+rm ./data/openlayers-function-click.sql

examples/docker/load-data.sh

@@ -0,0 +1,3 @@
+POSTGRES_USER=tileserv
+POSTGRES_PASSWORD=tileserv
+POSTGRES_DB=tileserv

examples/docker/pg.env

@@ -0,0 +1 @@
+DATABASE_URL=postgres://tileserv:tileserv@pg_tileserv_db/tileserv