Service Instance Creation and Configuration

Speaking of EOxServer we distinguish the common EOxServer installation (the installed code implementing the software functionality) and EOxServer instances. An instance is a collection of data and configuration files that enables the deployment of a specific service. A single server will typically contain a single software installation and one or more specific instances.

This section deals with the creation and configuration of EOxServer instances.

See also

Instance Creation

To create an instance, we recommend to use the script that comes with EOxServer:

Usage: [options] INSTANCE_ID [Optional destination directory]

Creates a new EOxServer instance with name INSTANCE_ID in the current or optionally given directory with all necessary files and folder structure. If the --init-spatialite flag is set, then an initial sqlite database will be created and initialized.


-h, --help show this help message and exit
 Flag to initialize the sqlite database.

Instance Configuration

Every EOxServer instance has various configuration files:

For each of them there is a template in the eoxserver/instance_template directory of the EOxServer distribution (referenced above) which is copied and adjusted by the script to the instance directory. If you create an EOxServer instance without the script you can copy those files and edit them yourself.

The file contains the Django configuration. Settings that need to be customized:

  • PROJECT_DIR: Absolute path to the instance directory.
  • DATABASES: The database connection details. For detailed information see Database Setup
  • COMPONENTS: The EOxServer components enabled for this instance. This is the main way how the active functionality of EOxServer is controlled, and also a way to extend the existing capabilities with extensions. Please refer to the Plugins section to see how this is done. By default all available components are enabled.
  • LOGGING: what and how logs are prcessed and stored. EOxServer provides a very basic configuration that stores logfiles in the instace directory, but they will probably not be suitable for every instance.

You can also customize further settings, for a complete reference please refer to the Django settings overview.

Please especially consider the setting of the TIME_ZONE parameter and read the Notes provided in the file.

The file conf/eoxserver.conf contains EOxServer specific settings. Please refer to the configuration options section for details.

Once you have created an instance, you have to configure and synchronize the database. If you are using the script with the --init-spatialite flag, all you have to do is:

  • Make sure EOxServer is on your PYTHONPATH environment variable

  • run in your instance directory:

    python syncdb

This script will also create an administration user if you want to. Note the username and password you provide. You’ll need it to log in to the admin client.

You can always create a user at a later time by running python createsuperuser.

Database Setup

This section is only needed if the --init_spatialite flag was not used during instance creation or a PostgreSQL/PostGIS database back-end shall be used. Before proceeding, please make sure that you have installed all required software for the database system of your choice.

Using a SQLite database, all you have to do is to copy the TEMPLATE_config.sqlite and place it somewhere in your instance directory. Now you have to edit the DATABASES of your file with the following lines:

    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.spatialite',
        'NAME': '/path/to/config.sqlite',

Using a PostgreSQL/PostGIS database back-end configuration for EOxServer is a little bit more complex. Setting up a PostgreSQL database requires also installing the PostGIS extensions (the following example is an installation based on a Debian system):

sudo su - postgres
POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
createlang plpgsql $POSTGIS_DB_NAME
psql -d $POSTGIS_DB_NAME -f $POSTGIS_SQL_PATH/postgis.sql
psql -d $POSTGIS_DB_NAME -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
psql -d $POSTGIS_DB_NAME -c "GRANT ALL ON geometry_columns TO PUBLIC;"
psql -d $POSTGIS_DB_NAME -c "GRANT ALL ON geography_columns TO PUBLIC;"
psql -d $POSTGIS_DB_NAME -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"

This creates the database and installs the PostGIS extensions within the database. Now a user with password can be set with the following line:

createuser -d -R -P -S eoxserver-admin

Depending on the configuration of the system used there may be the need to enable access for the user in the pg_hba.conf.

In the the following entry has to be added:

    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.postgis',
        'NAME': 'eoxserver_db',
        'USER': 'eoxserver-admin',
        'PASSWORD': 'eoxserver',
        'HOST': 'localhost',    # or the URL of your server hosting the DB
        'PORT': '',

Please refer to GeoDjango Database API for more instructions.


EOxServer is deployed using the Python WSGI interface standard as any other Django application. The WSGI endpoint accepts HTTP requests passed from the web server and processes them synchronously. Each request is executed independently.

In the deployment git repository we collect snippets for various deployment scenarios.

In the following we present the way to deploy it using the Apache2 Web Server and its mod_wsgi extension module.

The deployment procedure consists of the following:

  • Customize the Apache2 configuration file, e.g. /etc/apache2/sites-enabled/000-default, by adding:

    Alias /<url> <absolute path to instance dir>/
    <Directory "<absolute path to instance dir>">
            AllowOverride None
            Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
            AddHandler wsgi-script .py
            Order Allow,Deny
            Allow from all
  • If using EOxServer < 0.3 customize in your EOxServer instance and add:

    import sys
    path = "<absolute path to instance dir>"
    if path not in sys.path:
  • Restart the Web Server

As a general good idea the number of threads can be limited using the following additional Apache2 configuration. In case an old version of MapServer, i.e. < 6.2 or < 6.0.4, is used the number of threads needs to be limited to 1 to avoid some thread safety issues:

WSGIDaemonProcess ows processes=10 threads=1
<Directory "<absolute path to instance dir>">
    WSGIProcessGroup ows

This setup will deploy your instance under the URL <url> and make it publicly accessible.

Finally all the static files need to be collected at the location configured by STATIC_ROOT in by using the following command from within your instance:

python collectstatic

Don’t forget to update the static files by re-running above command if needed.

Data Registration

To insert data into an EOxServer instance there are several ways. One is the admin interface, which is explained in detail in the Admin Client section.

Another convenient way to register datasets is the command line interface to EOxServer. As a Django application, the instance can be configured using the script.

EOxServer provides a specific command to insert datasets into the instance, called eoxs_dataset_register. It is invoked from command line from your instance base folder:

python eoxs_dataset_register --data DATAFILES --range-type RANGETYPE

The mandatory parameter --data is a path to a file containing the raster data for the dataset to be inserted. If the file resides in a package (a ZIP or TAR archive) then the location must be preceeded with the following: <package-type>:<package-location>. It also possible to chain multiple packages, e.g a ZIP file in a ZIP file containing the actual raster data. In conjunction to packages, it is also possible to state the storage of the data files. By default it is assumed that the data is available locally, but other storages (such as FTP or HTTP backends) are also possible. If used, it must be declared as first item in the aforementioned in the chain.

For each --data item a --semantic can be stated. The semantic defines how this data item is being used. For example a semantic of "bands[1:3]" defines that the first three bands of the dataset is in the first data item.

The same rules also apply for files declared via the --meta-data directive. This basically creates a --data item with "metadata" semantic. Also, these files are preferred when trying to determine the mandatory metadata of a dataset.

To specify the Range Type of the dataset, the --range-type parameter is mandatory to specify the name of a previously registered Range Type.

The following options are used to supply metadata values that are either not possible to retrieve automatically or are to overwrite values automatically collected:

  • --identifier: the main identifier of the dataset
  • --extent: the (minx,miny,maxx,maxy) bounding box of the dataset
    expressed in the units defined in --srid or --projection
  • --size: the pixel size of the dataset (size_x,size_y)
  • --srid or --projection: the native projection of the dataset
  • --footprint: the footprint (multi-) polygon in WKT format
  • --begin-time and --end-time: the datasets time span
  • --coverage-type: the type of the dataset

By default, a dataset is not advertised in WMS/WCS GetCapabilities. In order to enable this, use the --visible flag.

When this dataset shall be inserted into a collection, use the --collection option with the collections identifier. This option can be set multiple times for different collections.