kopia lustrzana https://github.com/kartoza/docker-postgis
Updated comments in docker-compose.yml (#165)
* Removed useless comment * Updated comment about extensions * Added doc for ogr_fdw,pointcloud,pointcloud_postgis extensionspull/170/head^2
pierrealixt
mazano
rodzic
0437e00580
commit
39d21525a4
111
README.md
111
README.md
|
|
@ -19,8 +19,8 @@ differentiates itself by:
|
|||
* Gdal drivers automatically registered for pg raster
|
||||
* Support for out-of-db rasters
|
||||
|
||||
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
|
||||
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).
|
||||
|
||||
There is a nice 'from scratch' tutorial on using this docker image on Alex Urquhart's
|
||||
|
|
@ -81,12 +81,15 @@ docker build -t kartoza/postgis .
|
|||
## Build with custom extensions
|
||||
The plugin currently install PostGIS official extensions but in some cases users
|
||||
need to build custom extension. Add your build instructions to pg_extensions.sh
|
||||
and then run
|
||||
and then run
|
||||
|
||||
```
|
||||
docker build --build-args PG_EXTENSION=true -t kartoza/postgis:12.0 .
|
||||
```
|
||||
|
||||
The image is currently built to accommodate the following extensions `ogr_fdw`,`pointcloud`,`pointcloud_postgis` which you can use by with the environment variable
|
||||
`POSTGRES_MULTIPLE_EXTENSIONS`.
|
||||
|
||||
## Run
|
||||
|
||||
|
||||
|
|
@ -98,10 +101,10 @@ sudo docker run --name "postgis" -p 25432:5432 -d -t kartoza/postgis
|
|||
|
||||
## Environment variables
|
||||
|
||||
You can also use the following environment variables to pass a
|
||||
You can also use the following environment variables to pass a
|
||||
user name, password and/or default database name(or multiple databases comma separated).
|
||||
|
||||
* -e POSTGRES_USER=<PGUSER>
|
||||
* -e POSTGRES_USER=<PGUSER>
|
||||
* -e POSTGRES_PASS=<PGPASSWORD>
|
||||
* -e POSTGRES_DBNAME=<PGDBNAME>
|
||||
* -e POSTGRES_MULTIPLE_EXTENSIONS=postgis,hstore,postgis_topology,pointcloud,pointcloud_postgis # You can pass as many extensions as you need.
|
||||
|
|
@ -125,16 +128,16 @@ Specifies the maximum amount of memory to be used by maintenance operations, suc
|
|||
* -e MAINTAINANCE_WORK_MEM=128MB
|
||||
|
||||
These will be used to create a new superuser with
|
||||
your preferred credentials. If these are not specified then the postgresql
|
||||
your preferred credentials. If these are not specified then the postgresql
|
||||
user is set to 'docker' with password 'docker'.
|
||||
|
||||
You can open up the PG port by using the following environment variable. By default
|
||||
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> By default
|
||||
* -e ALLOW_IP_RANGE=<0.0.0.0/0> By default
|
||||
|
||||
Postgres conf is setup to listen to all connections and if a user needs to restrict which IP address
|
||||
PostgreSQL listens to you can define it with the following environment variable. The default is set to listen to
|
||||
PostgreSQL listens to you can define it with the following environment variable. The default is set to listen to
|
||||
all connections.
|
||||
* -e IP_LIST=<*>
|
||||
|
||||
|
|
@ -146,7 +149,7 @@ You can also define any other configuration to add to `postgres.conf`, separated
|
|||
## Convenience docker-compose.yml
|
||||
|
||||
For convenience we have provided a ``docker-compose.yml`` that will run a
|
||||
copy of the database image and also our related database backup image (see
|
||||
copy of the database image and also our related database backup image (see
|
||||
[https://github.com/kartoza/docker-pg-backup](https://github.com/kartoza/docker-pg-backup)).
|
||||
|
||||
The docker compose recipe will expose PostgreSQL on port 25432 (to prevent
|
||||
|
|
@ -184,10 +187,10 @@ sudo apt-get install postgresql-client-12
|
|||
## Running SQL scripts on container startup.
|
||||
|
||||
|
||||
In some instances users want to run some SQL scripts to populate the
|
||||
In some instances users want to run some SQL scripts to populate the
|
||||
database. Since the environment variable POSTGRES_DB allows
|
||||
us to specify multiple database that can be created on startup.
|
||||
When running scripts they will only be executed against the
|
||||
When running scripts they will only be executed against the
|
||||
first database ie POSTGRES_DB=gis,data,sample
|
||||
The SQL script will be executed against the gis database.
|
||||
|
||||
|
|
@ -215,55 +218,55 @@ for the docker process to read / write it.
|
|||
## Postgres Replication Setup
|
||||
|
||||
Replication allows you to maintain two or more synchronised copies of a database, with a
|
||||
single **master** copy and one or more **replicant** copies. The animation below illustrates
|
||||
this - the layer with the red boundary is accessed from the master database and the layer
|
||||
with the green fill is accessed from the replicant database. When edits to the master
|
||||
layer are saved, they are automatically propagated to the replicant. Note also that the
|
||||
single **master** copy and one or more **replicant** copies. The animation below illustrates
|
||||
this - the layer with the red boundary is accessed from the master database and the layer
|
||||
with the green fill is accessed from the replicant database. When edits to the master
|
||||
layer are saved, they are automatically propagated to the replicant. Note also that the
|
||||
replicant is read-only.
|
||||
|
||||
|
||||
|
||||
This image is provided with replication abilities. We can
|
||||
categorize an instance of the container as `master` or `replicant`. A `master`
|
||||
instance means that a particular container has a role as a single point of
|
||||
database write. A `replicant` instance means that a particular container will
|
||||
mirror database content from a designated master. This replication scheme allows
|
||||
us to sync databases. However a `replicant` is only for read-only transaction, thus
|
||||
This image is provided with replication abilities. We can
|
||||
categorize an instance of the container as `master` or `replicant`. A `master`
|
||||
instance means that a particular container has a role as a single point of
|
||||
database write. A `replicant` instance means that a particular container will
|
||||
mirror database content from a designated master. This replication scheme allows
|
||||
us to sync databases. However a `replicant` is only for read-only transaction, thus
|
||||
we can't write new data to it. The whole database cluster will be replicated.
|
||||
|
||||
### Database permissions
|
||||
Since we are using a role ${REPLICATION_USER}, we need to ensure that it has access to all
|
||||
Since we are using a role ${REPLICATION_USER}, we need to ensure that it has access to all
|
||||
the tables in a particular schema. So if a user adds another schema called `data`
|
||||
to the database `gis` he also has to update the permission for the user
|
||||
with the following SQL assuming the ${REPLICATION_USER} is called replicator
|
||||
|
||||
ALTER DEFAULT PRIVILEGES IN SCHEMA data GRANT SELECT ON TABLES TO replicator;
|
||||
|
||||
To experiment with the replication abilities, you can see a (docker-compose.yml)[sample/replication/docker-compose.yml]
|
||||
To experiment with the replication abilities, you can see a (docker-compose.yml)[sample/replication/docker-compose.yml]
|
||||
sample. There are several environment variables that you can set, such as:
|
||||
|
||||
Master settings:
|
||||
- **ALLOW_IP_RANGE**: A pg_hba.conf domain format which will allow specified host(s)
|
||||
to connect into the container. This is needed to allow the `slave` to connect
|
||||
into `master`, so specifically this settings should allow `slave` address. It is also needed to allow clients on other hosts to connect to either the slave or the master.
|
||||
- **ALLOW_IP_RANGE**: A pg_hba.conf domain format which will allow specified host(s)
|
||||
to connect into the container. This is needed to allow the `slave` to connect
|
||||
into `master`, so specifically this settings should allow `slave` address. It is also needed to allow clients on other hosts to connect to either the slave or the master.
|
||||
- **REPLICATION_USER** User to initiate streaming replication
|
||||
- **REPLICATION_PASS** Password for a user with streaming replication role
|
||||
|
||||
|
||||
Slave settings:
|
||||
- **REPLICATE_FROM**: This should be the domain name or IP address of the `master`
|
||||
instance. It can be anything from the docker resolved name like that written in the sample,
|
||||
or the IP address of the actual machine where you expose `master`. This is
|
||||
- **REPLICATE_FROM**: This should be the domain name or IP address of the `master`
|
||||
instance. It can be anything from the docker resolved name like that written in the sample,
|
||||
or the IP address of the actual machine where you expose `master`. This is
|
||||
useful to create cross machine replication, or cross stack/server.
|
||||
- **REPLICATE_PORT**: This should be the port number of `master` postgres instance.
|
||||
- **REPLICATE_PORT**: This should be the port number of `master` postgres instance.
|
||||
Will default to 5432 (default postgres port), if not specified.
|
||||
- **DESTROY_DATABASE_ON_RESTART**: Default is `True`. Set to 'False' to prevent
|
||||
this behaviour. A replicant will always destroy its current database on
|
||||
- **DESTROY_DATABASE_ON_RESTART**: Default is `True`. Set to 'False' to prevent
|
||||
this behaviour. A replicant will always destroy its current database on
|
||||
restart, because it will try to sync again from `master` and avoid inconsistencies.
|
||||
- **PROMOTE_MASTER**: Default none. If set to any value then the current replicant
|
||||
will be promoted to master.
|
||||
In some cases when the `master` container has failed, we might want to use our `replicant`
|
||||
as `master` for a while. However, the promoted replicant will break consistencies and
|
||||
is not able to revert to replicant anymore, unless it is destroyed and resynced
|
||||
- **PROMOTE_MASTER**: Default none. If set to any value then the current replicant
|
||||
will be promoted to master.
|
||||
In some cases when the `master` container has failed, we might want to use our `replicant`
|
||||
as `master` for a while. However, the promoted replicant will break consistencies and
|
||||
is not able to revert to replicant anymore, unless it is destroyed and resynced
|
||||
with the new master.
|
||||
- **REPLICATION_USER** User to initiate streaming replication
|
||||
- **REPLICATION_PASS** Password for a user with streaming replication role
|
||||
|
|
@ -276,7 +279,7 @@ Do a manual image build by executing the `build.sh` script
|
|||
./build.sh
|
||||
```
|
||||
|
||||
Go into the `sample/replication` directory and experiment with the following Make
|
||||
Go into the `sample/replication` directory and experiment with the following Make
|
||||
command to run both master and slave services.
|
||||
|
||||
```
|
||||
|
|
@ -300,7 +303,7 @@ You can try experiment with several scenarios to see how replication works
|
|||
|
||||
### Sync changes from master to replicant
|
||||
|
||||
You can use any postgres database tools to create new tables in master, by
|
||||
You can use any postgres database tools to create new tables in master, by
|
||||
connecting using POSTGRES_USER and POSTGRES_PASS credentials using exposed port.
|
||||
In the sample, the master database was exposed on port 7777.
|
||||
Or you can do it via command line, by entering the shell:
|
||||
|
|
@ -312,8 +315,8 @@ make master-shell
|
|||
Then made any database changes using psql.
|
||||
|
||||
After that, you can see that the replicant follows the changes by inspecting the
|
||||
slave database. You can, again, use database management tools using connection
|
||||
credentials, hostname, and ports for replicant. Or you can do it via command line,
|
||||
slave database. You can, again, use database management tools using connection
|
||||
credentials, hostname, and ports for replicant. Or you can do it via command line,
|
||||
by entering the shell:
|
||||
|
||||
```
|
||||
|
|
@ -325,23 +328,23 @@ Then view your changes using psql.
|
|||
### Promoting replicant to master
|
||||
|
||||
You will notice that you cannot make changes in replicant, because it is read-only.
|
||||
If somehow you want to promote it to master, you can specify `PROMOTE_MASTER: 'True'`
|
||||
into slave environment and set `DESTROY_DATABASE_ON_RESTART: 'False'`.
|
||||
If somehow you want to promote it to master, you can specify `PROMOTE_MASTER: 'True'`
|
||||
into slave environment and set `DESTROY_DATABASE_ON_RESTART: 'False'`.
|
||||
|
||||
After this, you can make changes to your replicant, but master and replicant will not
|
||||
be in sync anymore. This is useful if the replicant needs to take over a failover master.
|
||||
However it is recommended to take additional action, such as creating a backup from the
|
||||
After this, you can make changes to your replicant, but master and replicant will not
|
||||
be in sync anymore. This is useful if the replicant needs to take over a failover master.
|
||||
However it is recommended to take additional action, such as creating a backup from the
|
||||
slave so a dedicated master can be created again.
|
||||
|
||||
### Preventing replicant database destroy on restart
|
||||
|
||||
You can optionally set `DESTROY_DATABASE_ON_RESTART: 'False'` after successful sync
|
||||
to prevent the database from being destroyed on restart. With this setting you can
|
||||
shut down your replicant and restart it later and it will continue to sync using the existing
|
||||
You can optionally set `DESTROY_DATABASE_ON_RESTART: 'False'` after successful sync
|
||||
to prevent the database from being destroyed on restart. With this setting you can
|
||||
shut down your replicant and restart it later and it will continue to sync using the existing
|
||||
database (as long as there are no consistencies conflicts).
|
||||
|
||||
However, you should note that this option doesn't mean anything if you didn't
|
||||
persist your database volume. Because if it is not persisted, then it will be lost
|
||||
However, you should note that this option doesn't mean anything if you didn't
|
||||
persist your database volume. Because if it is not persisted, then it will be lost
|
||||
on restart because docker will recreate the container.
|
||||
|
||||
## Postgres SSL setup
|
||||
|
|
@ -387,7 +390,7 @@ The database cluster is initialised with the following encoding settings
|
|||
-E "UTF8" --lc-collate="en_US.UTF-8" --lc-ctype="en_US.UTF-8"
|
||||
`
|
||||
|
||||
If you need to setup a database cluster with other encoding parameters you need
|
||||
If you need to setup a database cluster with other encoding parameters you need
|
||||
to pass the environment variables
|
||||
|
||||
* -e DEFAULT_ENCODING="UTF8"
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
# docker-compose build
|
||||
# docker-compose up -d web
|
||||
version: '2.1'
|
||||
volumes:
|
||||
dbbackups:
|
||||
|
|
@ -19,7 +18,7 @@ services:
|
|||
- POSTGRES_PASS=docker
|
||||
- ALLOW_IP_RANGE=0.0.0.0/0
|
||||
# Add extensions you need to be enabled by default in the DB. Default are the three specified below
|
||||
- POSTGRES_MULTIPLE_EXTENSIONS=postgis,hstore,postgis_topology,ogr_fdw,pointcloud,pointcloud_postgis
|
||||
- POSTGRES_MULTIPLE_EXTENSIONS=postgis,hstore,postgis_topology
|
||||
ports:
|
||||
- 5434:5432
|
||||
restart: on-failure
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue