Installation and configuration¶
Prerequisites¶
Prerequisite | Version |
---|---|
Python with setuptools and pip | 3 [1] |
PostgreSQL + PostGIS + TimescaleDB | |
GDAL | 1.9 [2] |
[1] Enhydris runs on Python 3.5 or later. It does not run on Python 2. setuptools and pip are needed in order to install the rest of the Python modules.
[2] In theory, installing the prerequisites with pip will also install gdal. However it can be tricky to install and it’s usually easier to install a prepackaged version for your operating system.
Install Enhydris¶
Install Enhydris by cloning it and then installing the requirements
specified in requirements.txt
, probably in a virtualenv:
git clone https://github.com/openmeteo/enhydris.git
git checkout 3.0
virtualenv --system-site-packages --python=/usr/bin/python3 \
enhydris/venv
./enhydris/venv/bin/pip install -r requirements.txt
./enhydris/venv/bin/pip install -r requirements-dev.txt
Configure Enhydris¶
Create a Django settings file, either in
enhydris_project/settings/local.py
, or wherever you like. It
should begin with this:
from enhydris_project.settings.development import *
and then it should go on to override DEBUG
, SECRET_KEY
,
DATABASES
and STATIC_ROOT
. More settings you may want to
override are the Django settings and the Enhydris
settings.
On production you need to import from enhydris_project.settings
instead.
Create a spatially enabled database¶
(In the following examples, we use enhydris_db
as the database
name, and enhydris_user
as the PostgreSQL username. The user
should not be a super user, and not be allowed to create more users.
In production, it should not be allowed to create databases; in
testing, it should be allowed, in order to be able to run the unit
tests.)
Here is a Debian buster example:
# Install PostgreSQL and PostGIS
apt install postgis postgresql-11-postgis-2.5
# Install TimescaleDB (you need to add repositories in /etc/apt as
# explained in the TimescaleDB installation documentation)
apt install timescaledb-postgresql-11
timescaledb-tune
# Create database template
sudo -u postgres -s
createdb template_postgis
psql -d template_postgis -c "CREATE EXTENSION postgis;"
psql -d template_postgis -c \
"UPDATE pg_database SET datistemplate='true' \
WHERE datname='template_postgis';"
exit
# Create database
sudo -u postgres -s
createuser --pwprompt enhydris_user
createdb --template template_postgis --owner enhydris_user enhydris_db
exit
# Note: We don't need to install the timescaledb extension; the
Django migrations of Enhydris will do so automatically.
Here is a Windows example, assuming PostgreSQL is installed at the default location:
cd C:\Program Files\PostgreSQL\11\bin
createdb template_postgis
psql -d template_postgis -c "CREATE EXTENSION postgis;"
psql -d template_postgis -c "UPDATE pg_database SET datistemplate='true'
WHERE datname='template_postgis';"
createuser -U postgres --pwprompt enhydris_user
createdb --template template_postgis --owner enhydris_user enhydris_db
At some point, these commands will ask you for the password of the operating system user.
Note:
Initialize the database¶
In order to initialize your database and create the necessary database tables for Enhydris to run, run the following commands inside the Enhydris configuration directory:
python manage.py migrate
python manage.py createsuperuser
The above commands will also ask you to create a Enhydris superuser.
Start Django and Celery¶
Inside the Enhydris configuration directory, run the following command:
python manage.py runserver
The above command will start the Django development server and set it to listen to port 8000.
In addition, run the following to start Celery:
celery worker -A enhydris -l info --concurrency=1
Production¶
To use Enhydris in production, you need to setup a web server such as apache. This is described in detail in Deploying Django and in https://djangodeployment.com/.
You also need to start celery as a service.
Post-install configuration: domain name¶
After you run Enhydris, logon as a superuser, visit the admin panel,
go to Sites
, edit the default site, and enter your domain name
there instead of example.com
. Emails to users for registration
confirmation will contain links to that domain. Restart the
Enhydris (by restarting apache/gunicorn/whatever) after changing the
domain name.
Settings reference¶
These are the settings available to Enhydris, in addition to the Django settings.
-
REGISTRATION_OPEN
¶ If
True
, users can register, otherwise they have to be created by the administrator. The default isFalse
.(This setting is defined by
django-registration-redux
.)
-
ENHYDRIS_USERS_CAN_ADD_CONTENT
¶ If set to
True
, it enables all logged in users to add stations to the site, and edit the data of the stations they have entered. When set toFalse
(the default), only privileged users are allowed to add/edit/remove data from the db.See also
ENHYDRIS_OPEN_CONTENT
.
-
ENHYDRIS_OPEN_CONTENT
¶ If set to
True
, users who haven’t logged on can view timeseries data and station file (e.g. image) content. Otherwise, only logged on users can do so. Logged on users can always view everything.When this setting is
False
,REGISTRATION_OPEN
must obviously also be set toFalse
.
-
ENHYDRIS_MAP_BASE_LAYERS
¶ A dictionary of JavaScript definitions of base layers to use on the map. The default is:
{ "Open Street Map": r''' L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", { attribution: ( 'Map data © <a href="https://www.openstreetmap.org/">' + 'OpenStreetMap</a> contributors, ' + '<a href="https://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>' ), maxZoom: 18, }) ''', "Open Cycle Map": r''' L.tileLayer("https://{s}.tile.thunderforest.com/cycle/{z}/{x}/{y}.png", { attribution: ( 'Map data © <a href="https://www.openstreetmap.org/">' + 'OpenStreetMap</a> contributors, ' + '<a href="https://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>' ), maxZoom: 18, }) ''' }
-
ENHYDRIS_MAP_DEFAULT_BASE_LAYER
¶ The name of the base layer that is visible by default; it must be a key in data:ENHYDRIS_MAP_BASE_LAYERS. The default is “Open Street Map”.
-
ENHYDRIS_MAP_MIN_VIEWPORT_SIZE
¶ Set a value in degrees. When a geographical query has a bounding box with dimensions less than
ENHYDRIS_MAP_MIN_VIEWPORT_SIZE
, the map initially shown will be zoomed so that its dimension will be at leastENHYDRIS_MAP_MIN_VIEWPORT_SIZE²
. Useful when showing a single entity, such as a hydrometeorological station. Default value is 0.04, corresponding to an area approximately 4×4 km.
-
ENHYDRIS_MAP_DEFAULT_VIEWPORT
¶ A tuple containing the default viewport for the map in geographical coordinates, in cases of geographical queries that do not return anything. Format is (minlon, minlat, maxlon, maxlat) where lon and lat is in decimal degrees, positive for north/east, negative for west/south.
-
ENHYDRIS_SITE_STATION_FILTER
¶ This is a quick-and-dirty way to create a web site that only displays a subset of an Enhydris database. For example, the database of http://system.deucalionproject.gr/ is the same as that of http://openmeteo.org/; however, the former only shows stations relevant to the Deucalion project, because it has this setting:
ENHYDRIS_SITE_STATION_FILTER = {'owner__id__exact': '9'}
-
ENHYDRIS_STATIONS_PER_PAGE
¶ Number of stations per page for the pagination of the station list. The default is 100.
-
ENHYDRIS_CELERY_SEND_TASK_ERROR_EMAILS
¶ If this is
True
(the default), celery will email theADMINS
whenever an exception occurs, like Django does by default.