API Server Configuration Files¶

The server configuration files found are in the instance/ directory. There is one configuration file for each application and one global configuration file for the whole server.

Per-Application Configuration Files¶

The API server can serve multiple applications. “Application” is synonymous with “project”. An application (or project) typically is about one book of the New Testament.

Each application has one configuration file. The API server looks for configuration files in the instance/ directory. The files themselves must be named *.conf and the name must not begin with an underscore.

See also: Flask Configuration Handling 2 and Werkzeug Serving WSGI Applications 3.

API Server¶

APPLICATION_NAME¶

The name of the application (Project). eg. “Acts Phase 5”

The name appears in title bar in the client.

APPLICATION_ROOT¶

The api entrypoint. 2 eg. “acts/ph5/”.

This value is appended to the APPLICATION_ROOT configured in the global configuration file to yield the API entry point for this application.

This value must have exactly 2 segments, eg. “<project>/<phase>/”.

With the example values the API entrypoint for this application would be “http://localhost:5000/api/acts/ph5/”. The API entrypoint is typically proxied through an Apache or nginx server that does the TLS handling.

APPLICATION_DESCRIPTION¶

An optional longer description of the application. eg. “(= Phase 4 + CBGM)”.

It appears in the project selection list in the client.

BOOK¶

The book this application is about. eg. “Mark”.

For a list of books see: ntg_common/tools.py

READ_ACCESS¶

The role that has read access. eg. “editor”

For a description of roles see: User Management.

READ_ACCESS_PRIVATE¶: The role that can read editor’s notes. eg. “editor_acts”

WRITE_ACCESS¶: The role that can modify the project. eg. “editor_acts”

PGHOST¶: The Postgres host. eg. “localhost”

PGPORT¶: The Postgres port. eg. “5432”

PGDATABASE¶

The Postgres database. eg. “acts_ph5”

Each project is stored in its own database.

PGUSER¶

The Postgres user. eg. “ntg”

The server connects to the database as this user. The password for this user (and database) should be configured in the standard Postgres ~/.pgpass 1 file in the home directory of the user that owns the API server.

Import¶

The following entries are used by the scripts/cceh/import.py script only:

MYSQL_CONF¶

The mysql client configuration file. eg. ~/.my.cnf.ntg

This file contains the credentials to connect to the local mysql server. It should be readable only by the users that run the scripts/cceh/import.py script. The API server itself only connects to the Postgres and never to the mysql server. Example of file contents:

[mysql]
host="localhost"
user="ntg"
password="123456"
default-character-set="utf8"

MYSQL_GROUP¶: The group to read in the MYSQL_CONF file. eg. mysql

MYSQL_ECM_DB¶: The name of the ECM database. eg. ECM_Mark_Ph2

MYSQL_ATT_TABLES¶: A regular expression to find all “att” tables in the ECM database. eg. Mk\d+

MYSQL_LAC_TABLES¶: A regular expression to find all “lac” tables in the ECM database. eg. Mk\d+lac

MYSQL_NESTLE_DB¶: The name of the Leitzeile database. eg. Nestle29

MYSQL_NESTLE_TABLE¶: A regular expression to find all “leitzeile” tables in the Leitzeile database. eg. Nestle29

MYSQL_VG_DB¶: The name of the VarGen database. eg. VarGen_Mark_Ph2

Note

The VarGen database is optional. Without it, default priorities will be used. In this case set this variable to the same as the MYSQL_ECM_DB variable and do not set any of the following variables.

MYSQL_LOCSTEM_TABLES¶: A regular expression to find all “locstemed” tables in the VarGen database. eg. LocStemEdMark\d+

MYSQL_RDG_TABLES¶: A regular expression to find all “rdg” tables in the VarGen database. eg. RdgMark\d+

MYSQL_VAR_TABLES¶: A regular expression to find all “var” tables in the VarGen database. eg. VarGenAttMark\d+

MYSQL_MEMO_TABLE¶: A regular expression to find all “memo” tables in the VarGen database. eg. Memo

Global Configuration File¶

This is the configuration file for the whole application server. The global configuration file must be named instance/_global.conf.

APPLICATION_HOST¶: The app server DNS name: eg. “localhost”

APPLICATION_PORT¶: The app server port. eg. 5000

APPLICATION_ROOT¶

The root API entrypoint. 2 eg. “/api/”

With the above mentioned values the API root entrypoint would be “http://localhost:5000/api/”. Application-specific entrypoints are appended to this root. The API entrypoint is typically proxied through an Apache or nginx server that does the TLS handling.

AFTER_LOGIN_URL¶: The URL to redirect the user to after she has logged in. eg. “https://ntg.uni-muenster.de/”

SECRET_KEY¶: Session cookie encryption. 2 eg. “a_long_random_secret_phrase”

USE_RELOADER¶

Should the server automatically restart the python process if modules were changed? 3 eg. True

Development only. Do not use in production servers.

USE_DEBUGGER¶

Should the werkzeug debugging system be used? 3 eg. True

Starts the web-debugger on Python exceptions. Development only. Do not use in production servers.

PGHOST¶: The Postgres host. eg. “localhost”

PGPORT¶: The Postgres port. eg. “5432”

PGDATABASE¶

The Postgres database that holds user login information. eg. “ntg_user”

This should be the database that holds only the user login information.

PGUSER¶

The Postgres user eg. “ntg”

The server connects to the database as this user. The password for this user (and database) should be configured in the standard Postgres ~/.pgpass 1 file in the home directory of the user that owns the API server.

USER_PASSWORD_HASH¶: The hash algorithm used to encrypt user passwords in the database. eg. “pbkdf2_sha512”

USER_PASSWORD_SALT¶: The salt used to encrypt the user passwords stored in the database. eg. “a_different_long_random_secret_phrase”

MAIL_SERVER¶: The mail server used to send user registration confirmation email. eg. “smtp.uni-muenster.de”

MAIL_PORT¶: The mail server port. eg. 25

MAIL_USE_TLS¶: Send mail using TLS. eg. True

MAIL_DEFAULT_SENDER¶: The sender name to use in the user registration confirmation emails. eg. “ntg appserver <noreply@uni-muenster.de>”

CORS_ALLOW_ORIGIN¶: Restricts API usage to specified hosts. eg. “*”

Footnotes¶

1(1,2): PostgreSQL Documentation: The Password File. https://www.postgresql.org/docs/current/libpq-pgpass.html
2(1,2,3,4): Flask Documentation: Configuration Handling. https://flask.palletsprojects.com/en/1.1.x/config/
3(1,2,3): Werkzeug Documentation: Serving WSGI Applications. https://werkzeug.palletsprojects.com/en/1.0.x/serving/