2014-05-04 19:14:46 +00:00
|
|
|
# docker-postgis
|
2014-05-04 18:52:28 +00:00
|
|
|
|
2015-08-11 09:14:55 +00:00
|
|
|
|
2015-08-11 09:10:48 +00:00
|
|
|
|
2014-05-04 19:14:46 +00:00
|
|
|
A simple docker container that runs PostGIS
|
|
|
|
|
2014-12-06 04:50:34 +00:00
|
|
|
Visit our page on the docker hub at: https://registry.hub.docker.com/u/kartoza/postgis/
|
|
|
|
|
2014-08-05 09:16:50 +00:00
|
|
|
There are a number of other docker postgis containers out there. This one
|
|
|
|
differentiates itself by:
|
|
|
|
|
|
|
|
* provides ssl support out of the box
|
|
|
|
* connections are restricted to the docker subnet
|
|
|
|
* template_postgis database template is created for you
|
2017-01-20 15:32:24 +00:00
|
|
|
* a default database 'gis' is created for you so you can use this container 'out of the
|
2014-08-05 09:16:50 +00:00
|
|
|
box' when it runs with e.g. QGIS
|
|
|
|
|
|
|
|
We will work to add more security features to this container in the future with
|
|
|
|
the aim of making a PostGIS image that is ready to be used in a production
|
|
|
|
environment (though probably not for heavy load databases).
|
|
|
|
|
2014-05-04 19:35:49 +00:00
|
|
|
**Note:** We recommend using ``apt-cacher-ng`` to speed up package fetching -
|
|
|
|
you should configure the host for it in the provided 71-apt-cacher-ng file.
|
2014-05-04 19:14:46 +00:00
|
|
|
|
2015-08-11 09:14:55 +00:00
|
|
|
## Tagged versions
|
|
|
|
|
|
|
|
The following convention is used for tagging the images we build:
|
|
|
|
|
|
|
|
kartoza/postgis:[postgres_version]-[postgis-version]
|
|
|
|
|
|
|
|
So for example:
|
|
|
|
|
2016-06-28 08:10:03 +00:00
|
|
|
``kartoza/postgis:9.5-2.2`` Provides PostgreSQL 9.5, PostGIS 2.2
|
2015-08-11 09:14:55 +00:00
|
|
|
|
|
|
|
**Note:** We highly recommend that you use tagged versions because
|
|
|
|
successive minor versions of PostgreSQL write their database clusters
|
|
|
|
into different database directories - which will cause your database
|
|
|
|
to appear to be empty if you are using persistent volumes for your
|
|
|
|
database storage.
|
|
|
|
|
2014-09-10 11:17:37 +00:00
|
|
|
## Getting the image
|
2014-05-04 19:14:46 +00:00
|
|
|
|
2014-09-10 11:17:37 +00:00
|
|
|
There are various ways to get the image onto your system:
|
|
|
|
|
|
|
|
|
|
|
|
The preferred way (but using most bandwidth for the initial image) is to
|
|
|
|
get our docker trusted build like this:
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
docker pull kartoza/postgis
|
|
|
|
```
|
|
|
|
|
|
|
|
To build the image yourself without apt-cacher (also consumes more bandwidth
|
|
|
|
since deb packages need to be refetched each time you build) do:
|
2014-05-04 19:14:46 +00:00
|
|
|
|
|
|
|
```
|
2014-08-05 09:16:50 +00:00
|
|
|
docker build -t kartoza/postgis git://github.com/kartoza/docker-postgis
|
2014-05-04 19:47:26 +00:00
|
|
|
```
|
|
|
|
|
2014-09-10 11:17:37 +00:00
|
|
|
To build with apt-cache (and minimised download requirements) do you need to
|
|
|
|
clone this repo locally first and modify the contents of 71-apt-cacher-ng to
|
|
|
|
match your cacher host. Then build using a local url instead of directly from
|
|
|
|
github.
|
2014-05-04 19:47:26 +00:00
|
|
|
|
|
|
|
```
|
2014-09-10 11:17:37 +00:00
|
|
|
git clone git://github.com/kartoza/docker-postgis
|
2014-05-04 19:47:26 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Now edit ``71-apt-cacher-ng`` then do:
|
|
|
|
|
|
|
|
```
|
2014-05-04 20:31:00 +00:00
|
|
|
docker build -t kartoza/postgis .
|
2014-05-04 19:14:46 +00:00
|
|
|
```
|
|
|
|
|
2014-05-04 20:31:00 +00:00
|
|
|
## Run
|
|
|
|
|
2014-05-04 19:14:46 +00:00
|
|
|
|
|
|
|
To create a running container do:
|
|
|
|
|
|
|
|
```
|
2014-08-05 09:16:50 +00:00
|
|
|
sudo docker run --name "postgis" -p 25432:5432 -d -t kartoza/postgis
|
2014-05-04 19:14:46 +00:00
|
|
|
```
|
|
|
|
|
2016-09-06 07:15:07 +00:00
|
|
|
## Environment variables
|
|
|
|
|
2014-10-02 14:52:45 +00:00
|
|
|
You can also use the following environment variables to pass a
|
2017-01-20 15:32:24 +00:00
|
|
|
user name, password and/or default database name.
|
2014-10-02 14:52:45 +00:00
|
|
|
|
2014-12-05 16:00:20 +00:00
|
|
|
* -e POSTGRES_USER=<PGUSER>
|
|
|
|
* -e POSTGRES_PASS=<PGPASSWORD>
|
2017-01-20 15:32:24 +00:00
|
|
|
* -e POSTGRES_DBNAME=<PGDBNAME>
|
2014-10-02 14:52:45 +00:00
|
|
|
|
|
|
|
These will be used to create a new superuser with
|
|
|
|
your preferred credentials. If these are not specified then the postgresql
|
|
|
|
user is set to 'docker' with password 'docker'.
|
|
|
|
|
2016-09-06 07:14:20 +00:00
|
|
|
You can open up the PG port by using the following environment variable. By default
|
|
|
|
the container will allow connections only from the docker private subnet.
|
|
|
|
|
|
|
|
* -e ALLOW_IP_RANGE=<0.0.0.0/0>
|
|
|
|
|
|
|
|
|
2014-10-02 14:52:45 +00:00
|
|
|
## Convenience run script
|
|
|
|
|
|
|
|
For convenience we have provided a bash script for running this container
|
|
|
|
that lets you specify a volume mount point and a username / password
|
|
|
|
for the new instance superuser. It takes these options:
|
|
|
|
|
|
|
|
```
|
|
|
|
OPTIONS:
|
|
|
|
-h Show this message
|
|
|
|
-n Container name
|
|
|
|
-v Volume to mount the Postgres cluster into
|
2017-03-27 06:11:18 +00:00
|
|
|
-l local port (defaults to 25432)
|
2014-10-02 14:52:45 +00:00
|
|
|
-u Postgres user name (defaults to 'docker')
|
|
|
|
-p Postgres password (defaults to 'docker')
|
2017-03-27 06:11:18 +00:00
|
|
|
-d database name (defaults to 'gis')
|
2014-10-02 14:52:45 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Example usage:
|
|
|
|
|
|
|
|
```
|
2017-03-27 06:11:18 +00:00
|
|
|
./run-postgis-docker.sh -p 6789 -v /tmp/foo/ -n postgis -u foo -p bar
|
2014-10-02 14:52:45 +00:00
|
|
|
|
|
|
|
```
|
|
|
|
|
2014-05-04 19:14:46 +00:00
|
|
|
## Connect via psql
|
|
|
|
|
|
|
|
Connect with psql (make sure you first install postgresql client tools on your
|
|
|
|
host / client):
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
psql -h localhost -U docker -p 25432 -l
|
|
|
|
```
|
|
|
|
|
2014-05-04 20:31:00 +00:00
|
|
|
**Note:** Default postgresql user is 'docker' with password 'docker'.
|
|
|
|
|
2014-05-04 19:14:46 +00:00
|
|
|
You can then go on to use any normal postgresql commands against the container.
|
|
|
|
|
|
|
|
Under ubuntu 14.04 the postgresql client can be installed like this:
|
|
|
|
|
|
|
|
```
|
2016-09-06 10:06:47 +00:00
|
|
|
sudo apt-get install postgresql-client-9.5
|
2014-05-04 19:14:46 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
2014-05-04 20:31:00 +00:00
|
|
|
## Storing data on the host rather than the container.
|
2014-05-04 19:14:46 +00:00
|
|
|
|
|
|
|
|
|
|
|
Docker volumes can be used to persist your data.
|
|
|
|
|
|
|
|
```
|
|
|
|
mkdir -p ~/postgres_data
|
|
|
|
docker run -d -v $HOME/postgres_data:/var/lib/postgresql kartoza/postgis`
|
|
|
|
```
|
|
|
|
|
2015-08-08 12:11:45 +00:00
|
|
|
You need to ensure the ``postgres_data`` directory has sufficient permissions
|
2014-05-04 19:14:46 +00:00
|
|
|
for the docker process to read / write it.
|
|
|
|
|
|
|
|
|
|
|
|
|
2014-05-04 20:31:00 +00:00
|
|
|
## Credits
|
|
|
|
|
2014-08-05 09:16:50 +00:00
|
|
|
Tim Sutton (tim@kartoza.com)
|
2014-05-04 19:14:46 +00:00
|
|
|
May 2014
|