- PostgreSQL 9.5 or later
- PostGIS 2.4 or later
The tile server depends on the ST_AsMVT() function, which is only available if PostGIS has been compiled with support for the libprotobuf library. See the output from PostGIS_Full_Version, for example:
POSTGIS="3.0.1" [EXTENSION] PGSQL="121" GEOS="3.8.0-CAPI-1.13.1 " PROJ="6.1.0" LIBXML="2.9.4" LIBJSON="0.13" LIBPROTOBUF="1.3.2" WAGYU="0.4.3 (Internal)"
You don’t need advanced knowledge in Postgres/PostGIS or web mapping to install
pg_tileserv and set up the examples in this guide. If you are new to functions in Postgres, you might try this quick interactive course to better see how you might take advantage of
We also link to further resources at the end of this guide, for your reference.
pg_tileserv, download the binary file. Alternatively, you may run a container. These first two options will suit most use cases; needing to build the executable from source is rare.
A. Download binaries
Builds of the latest code:
Unzip the file, copy the
pg_tileserv binary wherever you wish, or use it in place. If you move the binary, remember to move the
assets/ directory to the same location, or start the server using the
AssetsDir configuration option.
B. Run container
A Docker image is available on DockerHub:
When you run the container, provide the database connection information in the
DATABASE_URL environment variable and map the default service port (7800).
docker run -e DATABASE_URL=postgres://user:pass@host/dbname -p 7800:7800 pramsey/pg_tileserv
C. Build from source
SRC=$GOPATH/src/github.com/CrunchyData mkdir -p $SRC cd $SRC git clone firstname.lastname@example.org:CrunchyData/pg_tileserv.git cd pg_tileserv go build go install
To run the build, set the
DATABASE_URL environment variable to the database you want to connect to, and run the binary.
export DATABASE_URL=postgres://user:pass@host/dbname $GOPATH/bin/pg_tileserv
export DATABASE_URL=postgresql://username:password@host/dbname ./pg_tileserv
SET DATABASE_URL=postgresql://username:password@host/dbname pg_tileserv.exe
The configuration file will be automatically read from the following locations, if it exists:
- In the system configuration directory, at
- Relative to the directory from which the program is run,
If you want to pass a path directly to the configuration file, use the
--config command line parameter.
Configuration files in other locations will be ignored when using the
./pg_tileserv --config /opt/pg_tileserv/pg_tileserv.toml
The default settings will suit most uses, and the program autodetects values such as the server name.
# Database connection DbConnection = "user=you host=localhost dbname=yourdb" # Close pooled connections after this interval DbPoolMaxConnLifeTime = "1h" # Hold no more than this number of connections in the database pool DbPoolMaxConns = 4 # Look to read html templates from this directory AssetsPath = "./assets" # Accept connections on this subnet (default accepts on all subnets) HttpHost = "0.0.0.0" # Accept connections on this port HttpPort = 7800 # Advertise URLs relative to this server name # default is to look this up from incoming request headers # UrlBase = "http://yourserver.com/" # Resolution to quantize vector tiles to DefaultResolution = 4096 # Rendering buffer to add to vector tiles DefaultBuffer = 256 # Limit number of features requested (-1 = no limit) MaxFeaturesPerTile = 10000 # Advertise this minimum zoom level DefaultMinZoom = 0 # Advertise this maximum zoom level DefaultMaxZoom = 22 # Allow any page to consume these tiles CORSOrigins = * tra logging information? Debug = false