|
| 1 | +# postgis/postgis |
| 2 | + |
| 3 | +[](https://github.com/postgis/docker-postgis/actions) [](https://gitter.im/postgis/docker-postgis?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
| 4 | + |
| 5 | +The `postgis/postgis` image provides tags for running Postgres with [PostGIS](http://postgis.net/) extensions installed. This image is based on the official [`postgres`](https://registry.hub.docker.com/_/postgres/) image and provides debian and alpine variants for PostGIS both 2.5.x and 3.1.x for each supported version of Postgres (9.5, 9.6, 10, 11, 12 and 13). Additionally, an image version is provided which is built from the latest version of Postgres (13) with versions of PostGIS and its dependencies built from their respective master branches. |
| 6 | + |
| 7 | +This image ensures that the default database created by the parent `postgres` image will have the following extensions installed: |
| 8 | + |
| 9 | +* `postgis` |
| 10 | +* `postgis_topology` |
| 11 | +* `postgis_tiger_geocoder` |
| 12 | + |
| 13 | +Note: As of PostGIS v3.x, raster has been factored out into a separate extension `postgis_raster` which must be installed separately. |
| 14 | + |
| 15 | +Unless `-e POSTGRES_DB` is passed to the container at startup time, this database will be named after the admin user (either `postgres` or the user specified with `-e POSTGRES_USER`). If you would prefer to use the older template database mechanism for enabling PostGIS, the image also provides a PostGIS-enabled template database called `template_postgis`. |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +In order to run a basic container capable of serving a PostGIS-enabled database, start a container as follows: |
| 20 | + |
| 21 | + docker run --name some-postgis -e POSTGRES_PASSWORD=mysecretpassword -d postgis/postgis |
| 22 | + |
| 23 | +For more detailed instructions about how to start and control your Postgres container, see the documentation for the `postgres` image [here](https://registry.hub.docker.com/_/postgres/). |
| 24 | + |
| 25 | +Once you have started a database container, you can then connect to the database either directly on the running container: |
| 26 | + |
| 27 | + docker exec -ti some-postgis psql -U postgres |
| 28 | + |
| 29 | +... or starting a new container to run as a client. In this case you can use a user-defined network to link both containers: |
| 30 | + |
| 31 | + docker network create some-network |
| 32 | + |
| 33 | + # Server container |
| 34 | + docker run --name some-postgis --network some-network -e POSTGRES_PASSWORD=mysecretpassword -d postgis/postgis |
| 35 | + |
| 36 | + # Client container |
| 37 | + docker run -it --rm --network some-network postgis/postgis psql -h some-postgis -U postgres |
| 38 | + |
| 39 | +Check the documentation on the [`postgres` image](https://registry.hub.docker.com/_/postgres/) and [Docker networking](https://docs.docker.com/network/) for more details and alternatives on connecting different containers. |
| 40 | + |
| 41 | +See [the PostGIS documentation](http://postgis.net/docs/postgis_installation.html#create_new_db_extensions) for more details on your options for creating and using a spatially-enabled database. |
| 42 | + |
| 43 | +## Known Issues / Errors |
| 44 | + |
| 45 | +When You encouter errors due to PostGIS update `OperationalError: could not access file "$libdir/postgis-X.X`, run: |
| 46 | + |
| 47 | +`docker exec some-postgis update-postgis.sh` |
| 48 | + |
| 49 | +It will update to Your newest PostGIS. Update is idempotent, so it won't hurt when You run it more than once, You will get notification like: |
| 50 | + |
| 51 | +``` |
| 52 | +Updating PostGIS extensions template_postgis to X.X.X |
| 53 | +NOTICE: version "X.X.X" of extension "postgis" is already installed |
| 54 | +NOTICE: version "X.X.X" of extension "postgis_topology" is already installed |
| 55 | +NOTICE: version "X.X.X" of extension "postgis_tiger_geocoder" is already installed |
| 56 | +ALTER EXTENSION |
| 57 | +Updating PostGIS extensions docker to X.X.X |
| 58 | +NOTICE: version "X.X.X" of extension "postgis" is already installed |
| 59 | +NOTICE: version "X.X.X" of extension "postgis_topology" is already installed |
| 60 | +NOTICE: version "X.X.X" of extension "postgis_tiger_geocoder" is already installed |
| 61 | +ALTER EXTENSION |
| 62 | +``` |
| 63 | + |
0 commit comments