Skip to content

Environment Variables

Environment Variables

A full list of environment variables are specified in the .env file

Default installed plugins

The image ships with the following stable plugins:

  • vectortiles-plugin
  • wps-plugin
  • printing-plugin
  • libjpeg-turbo-plugin
  • control-flow-plugin
  • pyramid-plugin
  • gdal-plugin
  • monitor-plugin
  • inspire-plugin
  • csw-plugin

Note: The plugins listed above are omitted from Stable_plugins.txt even though they are considered stable plugins The image activates them on startup.

The image provides the necessary plugin zip files which are used when activating the plugins. Not all the plugins will work out of the box because some plugins have extra dependencies which need to be downloaded and installed by users because of their licence terms i.e. db2

Some plugins also need extra configuration parameters i.e. community plugin s3-geotiff-plugin

Activate stable plugins during contain startup

The environment variable STABLE_EXTENSIONS can be used to activate plugins listed in Stable_plugins.txt

Example

ie VERSION=2.22.0
docker run -d -p 8600:8080 --name geoserver -e STABLE_EXTENSIONS=charts-plugin,db2-plugin kartoza/geoserver:${VERSION}

You can pass any comma-separated plugins as defined in the text file stable_plugins.txt

Note Due to the nature of the plugin ecosystem, there are new plugins that are always being upgraded from community extensions to stable extensions. If the stable_plugins.txt hasn't been updated with the latest changes you can still pass the environment variable with the name of the plugin. The plugin will be downloaded and installed. This might slow down the process of starting GeoServer but will ensure all plugins get activated

Activate community plugins during contain startup

The environment variable COMMUNITY_EXTENSIONS can be used to activate plugins listed in community_plugins.txt

Example

ie VERSION=2.22.0
docker run -d -p 8600:8080 --name geoserver -e COMMUNITY_EXTENSIONS=gwc-sqlite-plugin,ogr-datastore-plugin kartoza/geoserver:${VERSION}

You can also pass the environment variable FORCE_DOWNLOAD_COMMUNITY_EXTENSIONS=true to download the latest community plugins during initialisation of the container.

Note: Community plugins are always in flux state. There is no guarantee that plugins will be accessible between each successive build. You can build the extensions following the guidelines from GeoServer develop guidelines

Using sample data

Geoserver ships with sample data which can be used by users to familiarize them with software. This is not activated by default. You can activate it using the environment variable SAMPLE_DATA=true

ie VERSION=2.22.0
docker run -d -p 8600:8080 --name geoserver -e SAMPLE_DATA=true kartoza/geoserver:${VERSION}

Enable disk quota storage in PostgreSQL backend

GeoServer defaults to using H2 datastore for configuring disk quota. You can alternatively use the PostgreSQL backend as a disk quota store.

You will need to run a PostgreSQL DB and link it to a GeoServer instance.

docker run -d -p 5432:5432 --name db kartoza/postgis:13.0
docker run -d -p 8600:8080 --name geoserver --link db:db -e DB_BACKEND=POSTGRES -e HOST=db -e POSTGRES_PORT=5432 -e POSTGRES_DB=gis -e POSTGRES_USER=docker -e POSTGRES_PASS=docker kartoza/geoserver:2.18.0

Some additional environment variables to use when activating the disk quota are:

  • DISK_QUOTA_SIZE - Specifies the size of the disk quota you need to use. Defaults to 20Gb

If you are using the kartoza/docker-postgis image as a database backend you can additionally configure communication between the containers to use SSL

If you want to test it locally with docker-compose postgres db you need to specify these env variables:

    - DB_BACKEND=POSTGRES               
    - HOST=db                          
    - POSTGRES_PORT=5432                
    - POSTGRES_DB=gwc                   
    - POSTGRES_USER=${POSTGRES_USER}    
    - POSTGRES_PASS=${POSTGRES_PASS}    
    - SSL_MODE=allow                    
    - POSTGRES_SCHEMA=public           
    - DISK_QUOTA_SIZE=5

NOTE: 

HOST should be your local container name for db
POSTGRES_SCHEMA works only with 'public' right now

Using SSL and Default PostgreSQL ssl certificates

When the environment variable FORCE_SSL=TRUE is set for the database container you will need to set SSL_MODE=allow in the GeoServer container.

Using SSL certificates signed by a certificate authority

When the environment variable FORCE_SSL=TRUE is set for the database container you will need to set SSL_MODE to either verify-full or verify-ca for the GeoServer container. You will also need to mount the ssl certificates you have done in the DB.

In the GeoServer container, the certificates need to be mounted to the folder specified by the certificate directory ${CERT_DIR}

SSL_CERT_FILE=/etc/certs/fullchain.pem
SSL_KEY_FILE=/etc/certs/privkey.pem
SSL_CA_FILE=/etc/certs/root.crt

Activating JNDI PostgreSQL connector

When defining vector stores you can use the JNDI pooling. To set this up you will need to activate the following environment variable POSTGRES_JNDI=TRUE. By default, the environment the variable is set to FALSE Additionally, you will need to define parameters to connect to an existing PostgreSQL database

POSTGRES_JNDI=TRUE
HOST=${POSTGRES_HOSTNAME}
POSTGRES_DB=${POSTGRES_DB}
POSTGRES_USER=${POSTGRES_USER}
POSTGRES_PASS=${POSTGRES_PASS}

If you are using the kartoza/postgis image with the env variable FORCE_SSL=TRUE you will also need to set the environment variable SSL_MODE to correspond to value mentioned in kartoza/postgis ssl

When defining the parameters for the store in GeoServer you will need to set jndiReferenceName=java:comp/env/jdbc/postgres

Running under SSL

You can use the environment variables to specify whether you want to run the GeoServer under SSL. Credits to letsencrpt for providing the solution to run under SSL.

If you set the environment variable SSL=true but do not provide the pem files (fullchain.pem and privkey.pem) the container will generate a self-signed SSL certificates.

ie VERSION=2.22.0
docker run -it --name geoserver  -e PKCS12_PASSWORD=geoserver -e JKS_KEY_PASSWORD=geoserver -e JKS_STORE_PASSWORD=geoserver -e SSL=true -p 8443:8443 -p 8600:8080 kartoza/geoserver:${VERSION}

If you already have your perm files (fullchain.pem and privkey.pem) you can mount the directory containing your keys as:

ie VERSION=2.22.0
docker run -it --name geo -v /etc/certs:/etc/certs  -e PKCS12_PASSWORD=geoserver -e JKS_KEY_PASSWORD=geoserver -e JKS_STORE_PASSWORD=geoserver -e SSL=true -p 8443:8443 -p 8600:8080 kartoza/geoserver:${VERSION}

You can also use a PFX file with this image. Rename your PFX file as certificate.pfx and then mount the folder containing your pfx file. This will be converted to perm files.

Note When using PFX files make sure that the ALIAS_KEY you specify as an environment variable matches the ALIAS_KEY that was used when generating your PFX key.

A full list of SSL variables is provided here

  • HTTP_PORT
  • HTTP_PROXY_NAME
  • HTTP_PROXY_PORT
  • HTTP_REDIRECT_PORT
  • HTTP_CONNECTION_TIMEOUT
  • HTTP_COMPRESSION
  • HTTP_SCHEME
  • HTTP_MAX_HEADER_SIZE
  • HTTP_RELAX_CHARS
  • HTTP_RELAX_QUERY
  • HTTPS_SCHEME
  • HTTPS_PORT
  • HTTPS_MAX_THREADS
  • HTTPS_CLIENT_AUTH
  • HTTPS_PROXY_NAME
  • HTTPS_PROXY_PORT
  • HTTPS_COMPRESSION
  • HTTPS_MAX_HEADER_SIZE
  • JKS_FILE
  • JKS_KEY_PASSWORD
  • KEY_ALIAS
  • JKS_STORE_PASSWORD
  • P12_FILE

Proxy Base URL

For the server to report a full proxy base url, you need to pass the following env variable i.e.

HTTP_PROXY_NAME
HTTP_PROXY_PORT

If you are running GeoServer under SSL with reverse proxy i.e nginx you will need to set the following env variables

Example below:

HTTP_PROXY_NAME=foo.org
HTTP_SCHEME=https

This will prevent the login form from sending insecure http post request as experienced in login issue

For SSL based connections the env variables are:

HTTPS_PROXY_NAME
HTTPS_PROXY_PORT
HTTPS_SCHEME

Removing Tomcat extras

To include Tomcat extras including docs, examples, and the manager webapp, set the TOMCAT_EXTRAS environment variable to true:

Note: If TOMCAT_EXTRAS is set to true then you should configure TOMCAT_PASSWORD to use a strong password otherwise the default one is set up.

ie VERSION=2.22.0
docker run -it --name geoserver  -e TOMCAT_EXTRAS=true -p 8600:8080 kartoza/geoserver:${VERSION}

Note: If TOMCAT_EXTRAS is set to false, requests to the root webapp ("/") will return HTTP status code 404. To issue a redirect to the GeoServer webapp ("/geoserver/web") set ROOT_WEBAPP_REDIRECT=true

Upgrading image to use a specific version

During initialization, the image will run a script that updates the passwords. This is recommended to change passwords the first time that GeoServer runs. If you are migrating your GeoServer instance, from one a lower version to a higher one you will need to set the environment variable EXISTING_DATA_DIR; unset it to run the initialization script.

The environment variable will ensure that the password initialization is skipped during the startup procedure.

If you set the env variable EXISTING_DATA_DIR to any value i.e EXISTING_DATA_DIR=foo or EXISTING_DATA_DIR=false it will result in password update being skipped. So if you need to have the password being updated do not include the env variable in your configuration (this is the default configuration).

Installing extra fonts

If you have downloaded extra fonts you can mount the folder to the path /opt/fonts. This will ensure that all the .ttf files are copied to the correct path during initialisation.

ie VERSION=2.22.0
docker run -v fonts:/opt/fonts -p 8080:8080 -t kartoza/geoserver:${VERSION}

Other Environment variables supported

You can also use the following environment variables to pass arguments to GeoServer:

  • GEOSERVER_DATA_DIR=<PATH>
  • ENABLE_JSONP=<true or false>
  • MAX_FILTER_RULES=<Any integer>
  • OPTIMIZE_LINE_WIDTH=<false or true>
  • FOOTPRINTS_DATA_DIR=<PATH>
  • GEOWEBCACHE_CACHE_DIR=<PATH>
  • GEOSERVER_ADMIN_PASSWORD=<password>
  • GEOSERVER_ADMIN_USER=<username>
  • GEOSERVER_FILEBROWSER_HIDEFS=<false or true>
  • XFRAME_OPTIONS="true" - In order to prevent clickjacking attacks GeoServer defaults to setting the X-Frame-Options HTTP header to SAMEORIGIN. Controls whether the X-Frame-Options filter should be set at all. Default is true

  • Tomcat properties:

  • You can change the variables based on geoserver container considerations. These arguments operate on the -Xms and -Xmx options of the Java Virtual Machine

  • INITIAL_MEMORY=<size> : Initial Memory that Java can allocate, default 2G
  • MAXIMUM_MEMORY=<size> : Maximum Memory that Java can allocate, default 4G
  • ACTIVATE_ALL_COMMUNITY_EXTENSIONS : Activates all downloaded community plugins
  • ACTIVATE_ALL_STABLE_EXTENSIONS : Activates all stable plugins previously downloaded

Note: Before using ACTIVATE_ALL_STABLE_EXTENSIONS and ACTIVATE_ALL_COMMUNITY_EXTENSIONS ensure that all prerequisites for those plugins are matched otherwise the container will not start and errors will result

Control flow properties

The control flow module manages requests in GeoServer. Instructions on what each parameter mean can be read from documentation.

  • Example default values for the environment variables

    • REQUEST_TIMEOUT=60
    • PARALLEL_REQUEST=100
    • GETMAP=10
    • REQUEST_EXCEL=4
    • SINGLE_USER=6
    • GWC_REQUEST=16
    • WPS_REQUEST=1000/d;30s

Note: You should customise these variables based on the resources available with your GeoServer

Changing GeoServer password and username

You can pass the environment variables to change it on runtime.

GEOSERVER_ADMIN_PASSWORD
GEOSERVER_ADMIN_USER

The username and password are reinitialized each time the container starts. If you do not pass the env variables GEOSERVER_ADMIN_PASSWORD the container will generate a new password which is visible in the startup logs.

Note: When upgrading the GEOSERVER_ADMIN_PASSWORD and GEOSERVER_ADMIN_USER you will need to mount the volume settings:/settings so that the lock-files generated by the update_password.sh are persistent during initialization. See the example in docker-compose-build

docker run --name "geoserver" -e GEOSERVER_ADMIN_USER=kartoza  -e GEOSERVER_ADMIN_PASSWORD=myawesomegeoserver -p 8080:8080 -d -t kartoza/geoserver

Note: The docker-compose recipe uses the password myawesomegeoserver. It is highly recommended not to run the container in production using these values.

Docker secrets

To avoid passing sensitive information in environment variables, _FILE can be appended to some variables to read from files present in the container. This is particularly useful in conjunction with Docker secrets, as passwords can be loaded from /run/secrets/<secret_name> e.g.:

  • -e GEOSERVER_ADMIN_PASSWORD_FILE=/run/secrets/

For more information see https://docs.docker.com/engine/swarm/secrets/.

Currently, the following environment variables

 GEOSERVER_ADMIN_USER
 GEOSERVER_ADMIN_PASSWORD
 S3_USERNAME
 S3_PASSWORD
 TOMCAT_USER
 TOMCAT_PASSWORD
 PKCS12_PASSWORD
 JKS_KEY_PASSWORD
 JKS_STORE_PASSWORD

are supported.