add extended documentation of settings

[nominatim.git] / settings / env.defaults

diff --git a/settings/env.defaults b/settings/env.defaults
index 45b0fc6bdea1d9ce8cdd884d88e1caa7cf9aa216..3fb128dc78a05a0149bf4b5617267ed8cabb1abf 100644 (file)
--- a/settings/env.defaults
+++ b/settings/env.defaults
@@ -1,9 +1,11 @@
 # .env
 # .env

-# Default configuration settings for Nominatim
+# Default configuration settings for Nominatim.
+# This file uses the dotenv format.

 
 # Database connection string.
 # Add host, port, user etc through additional semicolon-separated attributes.
 # e.g. ;host=...;port=...;user=...;password=...
 
 # Database connection string.
 # Add host, port, user etc through additional semicolon-separated attributes.
 # e.g. ;host=...;port=...;user=...;password=...

+# Changing this variable requires to run 'nominatim refresh --website'.

 NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim"
 
 # Database web user.
 NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim"
 
 # Database web user.


@@ -11,115 +13,211 @@ NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim"
 NOMINATIM_DATABASE_WEBUSER="www-data"
 
 # Directory where to find the PostgreSQL server module.
 NOMINATIM_DATABASE_WEBUSER="www-data"
 
 # Directory where to find the PostgreSQL server module.

-# When a relative path is given, it will be searched relative to the project
-# directory.
-NOMINATIM_DATABASE_MODULE_PATH="module"
-
-#@define('CONST_Max_Word_Frequency', '50000');
-#@define('CONST_Limit_Reindexing', true);
-#// Restrict search languages.
-#// Normally Nominatim will include all language variants of name:XX
-#// in the search index. Set this to a comma separated list of language
-#// codes, to restrict import to a subset of languages.
-#// Currently only affects the import of country names and special phrases.
-#@define('CONST_Languages', false);
-#// Rules for normalizing terms for comparison before doing comparisons.
-#// The default is to remove accents and punctuation and to lower-case the
-#// term. Spaces are kept but collapsed to one standard space.
-#@define('CONST_Term_Normalization_Rules', ":: NFD (); [[:Nonspacing Mark:] [:Cf:]] >;  :: lower (); [[:Punctuation:][:Space:]]+ > ' '; :: NFC ();");
-#
-#/* Set to true after importing Tiger house number data for the US.
-#   Note: The tables must already exist or queries will throw errors.
-#         After changing this setting run ./utils/setup --create-functions
-#         again. */
-#@define('CONST_Use_US_Tiger_Data', false);
-#/* Set to true after importing other external house number data.
-#   Note: the aux tables must already exist or queries will throw errors.
-#        After changing this setting run ./utils/setup --create-functions
-#        again. */
-#@define('CONST_Use_Aux_Location_data', false);
-#
-#// Proxy settings
-#@define('CONST_HTTP_Proxy', false);
-#@define('CONST_HTTP_Proxy_Host', 'proxy.mydomain.com');
-#@define('CONST_HTTP_Proxy_Port', '3128');
-#@define('CONST_HTTP_Proxy_Login', '');
-#@define('CONST_HTTP_Proxy_Password', '');
-#
-#// Paths
-#@define('CONST_ExtraDataPath', CONST_BasePath.'/data');
-#@define('CONST_Osm2pgsql_Binary', CONST_InstallPath.'/osm2pgsql/osm2pgsql');
-#@define('CONST_Pyosmium_Binary', '@PYOSMIUM_PATH@');
-#@define('CONST_Tiger_Data_Path', CONST_ExtraDataPath.'/tiger');
-#@define('CONST_Wikipedia_Data_Path', CONST_ExtraDataPath);
-#@define('CONST_Phrase_Config', CONST_BasePath.'/settings/phrase_settings.php');
-#@define('CONST_Address_Level_Config', CONST_BasePath.'/settings/address-levels.json');
-#@define('CONST_Import_Style', CONST_BasePath.'/settings/import-full.style');
-#
-#// osm2pgsql settings
-#@define('CONST_Osm2pgsql_Flatnode_File', null);
-#
-#// tablespace settings
-#// osm2pgsql caching tables (aka slim mode tables) - update only
-#@define('CONST_Tablespace_Osm2pgsql_Data', false);
-#@define('CONST_Tablespace_Osm2pgsql_Index', false);
-#// osm2pgsql output tables (aka main table) - update only
-#@define('CONST_Tablespace_Place_Data', false);
-#@define('CONST_Tablespace_Place_Index', false);
-#// address computation tables - update only
-#@define('CONST_Tablespace_Address_Data', false);
-#@define('CONST_Tablespace_Address_Index', false);
-#// search tables - needed for lookups
-#@define('CONST_Tablespace_Search_Data', false);
-#@define('CONST_Tablespace_Search_Index', false);
-#// additional data, e.g. TIGER data, type searches - needed for lookups
-#@define('CONST_Tablespace_Aux_Data', false);
-#@define('CONST_Tablespace_Aux_Index', false);
-#
-#//// Replication settings
-#
-#// Base URL of replication service
-#@define('CONST_Replication_Url', 'https://planet.openstreetmap.org/replication/minute');
-#
-#// Maximum size in MB of data to download per batch
-#@define('CONST_Replication_Max_Diff_size', '30');
-#// How long until the service publishes the next diff
-#// (relative to the age of data in the diff).
-#@define('CONST_Replication_Update_Interval', '75');
-#// How long to sleep when no update could be found
-#@define('CONST_Replication_Recheck_Interval', '60');
-#
-#// If true, send CORS headers to allow access
-#@define('CONST_NoAccessControl', true);
+# When empty the module is expected to be located in the 'module' subdirectory
+# in the project directory.
+# Changing this value requires to run 'nominatim refresh --functions'.
+NOMINATIM_DATABASE_MODULE_PATH=
+
+# Tokenizer used for normalizing and parsing queries and names.
+# The tokenizer is set up during import and cannot be changed afterwards
+# without a reimport.
+# Currently available tokenizers: legacy
+NOMINATIM_TOKENIZER="legacy"
+
+# Number of occurrences of a word before it is considered frequent.
+# Similar to the concept of stop words. Frequent partial words get ignored
+# or handled differently during search.
+# Changing this value requires a reimport.
+NOMINATIM_MAX_WORD_FREQUENCY=50000
+
+# If true, admin level changes on places with many contained children are blocked.
+NOMINATIM_LIMIT_REINDEXING=yes
+
+# Restrict search languages.
+# Normally Nominatim will include all language variants of name:XX
+# in the search index. Set this to a comma separated list of language
+# codes, to restrict import to a subset of languages.
+# Currently only affects the initial import of country names and special phrases.
+NOMINATIM_LANGUAGES=
+
+# Rules for normalizing terms for comparisons.
+# The default is to remove accents and punctuation and to lower-case the
+# term. Spaces are kept but collapsed to one standard space.
+# Changing this value requires a reimport.
+NOMINATIM_TERM_NORMALIZATION=":: NFD (); [[:Nonspacing Mark:] [:Cf:]] >;  :: lower (); [[:Punctuation:][:Space:]]+ > ' '; :: NFC ();"
+
+# Configuration file for the tokenizer.
+# The content depends on the tokenizer used. If left empty the default settings
+# for the chosen tokenizer will be used. The configuration can only be set
+# on import and not be changed afterwards.
+NOMINATIM_TOKENIZER_CONFIG=
+
+# Search in the Tiger house number data for the US.
+# Note: The tables must already exist or queries will throw errors.
+# Changing this value requires to run ./utils/setup --create-functions --setup-website.
+NOMINATIM_USE_US_TIGER_DATA=no
+
+# Search in the auxiliary housenumber table.
+# Changing this value requires to run ./utils/setup --create-functions --setup-website.
+NOMINATIM_USE_AUX_LOCATION_DATA=no
+
+# Proxy settings
+# The following settings allow to set a proxy to use when remotely downloading
+# data. Host and port are required. Login and password are optional.
+NOMINATIM_HTTP_PROXY=no
+NOMINATIM_HTTP_PROXY_HOST=
+NOMINATIM_HTTP_PROXY_PORT=3128
+NOMINATIM_HTTP_PROXY_LOGIN=
+NOMINATIM_HTTP_PROXY_PASSWORD=
+# Also set these standard environment variables.
+# HTTP_PROXY="http://user:pass@10.10.1.10:1080"
+# HTTPS_PROXY="http://user:pass@10.10.1.10:1080"
+
+# Location of the osm2pgsql binary.
+# When empty, osm2pgsql is expected to reside in the osm2pgsql directory in
+# the project directory.
+# EXPERT ONLY. You should usually use the supplied osm2pgsql.
+NOMINATIM_OSM2PGSQL_BINARY=
+
+# Directory where to find US Tiger data files to import.
+# OBSOLETE: use `nominatim add-data --tiger-data <dir>` to explicitly state
+#           the directory on import
+NOMINATIM_TIGER_DATA_PATH=
+
+# Directory where to find pre-computed Wikipedia importance files.
+# When unset, the data is expected to be located in the project directory.
+NOMINATIM_WIKIPEDIA_DATA_PATH=
+
+# Configuration file for special phrase import.
+# When unset, the internal default settings from 'settings/phrase-settings.json'
+# are used.
+NOMINATIM_PHRASE_CONFIG=
+
+# Configuration file for rank assignments.
+# When unset, the internal default settings from 'settings/address-levels.json'
+# are used.
+NOMINATIM_ADDRESS_LEVEL_CONFIG=
+
+# Configuration file for OSM data import.
+# This may either be the name of one of an internal style or point
+# to a file with a custom style.
+# Internal styles are: admin, street, address, full, extratags
+NOMINATIM_IMPORT_STYLE=extratags
+
+# Location of the flatnode file used by osm2pgsql to store node locations.
+# When unset, osm2pgsql stores the location in the PostgreSQL database. This
+# is especially useful for imports of larger areas, like continents or the
+# full planet. The file needs at least 70GB storage.
+NOMINATIM_FLATNODE_FILE=
+
+### Tablespace settings

 #
 #

-#// Set this to the /mapicon directory of your nominatim-ui to enable returning
-#// icon URLs with the results.
-#@define('CONST_MapIcon_URL', false);
-#// Language to assume when none is supplied with the query.
-#// When set to false, the local language (i.e. the name tag without suffix)
-#// will be used.
-#@define('CONST_Default_Language', false);
+# The following settings allow to move parts of the database tables into
+# different tablespaces. This is especially interesting if you have disks
+# with different speeds. When unset, the default tablespace is used.
+# Only has an effect during import.
+
+# Tablespace used for tables used when searching.
+NOMINATIM_TABLESPACE_SEARCH_DATA=
+# Tablespace used for indexes used when searching.
+NOMINATIM_TABLESPACE_SEARCH_INDEX=
+
+# Tablespace used for the OSM data cache tables. Used for import and update only.
+NOMINATIM_TABLESPACE_OSM_DATA=
+# Tablespace used for the OSM data cache indexes. Used for import and update only.
+NOMINATIM_TABLESPACE_OSM_INDEX=
+
+# Tablespace used for place import table. Used for import and update only.
+NOMINATIM_TABLESPACE_PLACE_DATA=
+# Tablespace used for place import indexes. Used for import and update only.
+NOMINATIM_TABLESPACE_PLACE_INDEX=
+
+# Tablespace for tables used during address computation. Used for import and update only.
+NOMINATIM_TABLESPACE_ADDRESS_DATA=
+# Tablespace for indexes used during address computation. Used for import and update only.
+NOMINATIM_TABLESPACE_ADDRESS_INDEX=
+
+# Tablespace for tables for auxilary data, e.g. TIGER data, postcodes.
+NOMINATIM_TABLESPACE_AUX_DATA=
+# Tablespace for indexes for auxilary data, e.g. TIGER data, postcodes.
+NOMINATIM_TABLESPACE_AUX_INDEX=
+
+
+### Replication settings

 #
 #

-#@define('CONST_Search_AreaPolygons', true);
+# The following settings control where and how updates for the database are
+# retrieved.

 #
 #

-#@define('CONST_Search_BatchMode', false);
+

 #
 #

-#@define('CONST_Search_NameOnlySearchFrequencyThreshold', 500);
-#// If set to true, then reverse order of queries will be tried by default.
-#// When set to false only selected languages allow reverse search.
-#@define('CONST_Search_ReversePlanForAll', true);
+# Base URL of replication service.
+# A replication service provides change files of OSM data at regular intervals.
+# These are used to keep the database up to date. Per default it points to
+# the minutely updates for the main OSM database. There are other services
+# geared towards larger update intervals or data extracts.
+# Changing this value requires to rerun 'nominatim replication --init'.
+NOMINATIM_REPLICATION_URL="https://planet.openstreetmap.org/replication/minute"
+
+# Maximum amount of data to download per batch.
+# Size is in MB.
+NOMINATIM_REPLICATION_MAX_DIFF=50
+
+# Publication interval of the replication service (in seconds).
+# Determines when Nominatim will attempt again to download again a new
+# update. The time is computed from the publication date of the last diff
+# downloaded. Setting this to a slightly higher value than the actual
+# publication interval avoids unnecessary rechecks.
+NOMINATIM_REPLICATION_UPDATE_INTERVAL=75
+
+# Wait time to recheck for a pending update (in seconds).
+# Time to wait after an expected update was not available on the server.
+NOMINATIM_REPLICATION_RECHECK_INTERVAL=60
+
+### API settings

 #
 #

-#// Maximum number of OSM ids that may be queried at once
-#// for the places endpoint.
-#@define('CONST_Places_Max_ID_count', 50);
+# The following settings configure the API responses. You must rerun
+# 'nominatim refresh --website' after changing any of them.
+
+# Send permissive CORS access headers.
+# When enabled, send CORS headers to allow access to everybody.
+NOMINATIM_CORS_NOACCESSCONTROL=yes
+
+# URL for static icon images.
+# Set this to the /mapicon directory of your nominatim-ui to enable returning
+# icon URLs with the results.
+NOMINATIM_MAPICON_URL=
+
+# Language to assume when no particular language is requested.
+# When unset, the local language (i.e. the name tag without suffix) will be used.
+NOMINATIM_DEFAULT_LANGUAGE=
+
+# Enable a special batch query mode.
+# This feature is currently undocumented and potentially broken.
+NOMINATIM_SEARCH_BATCH_MODE=no
+
+# Threshold for searches by name only.
+# Threshold where the lookup strategy in the database is switched. If there
+# are less occurences of a tem than given, the search does the lookup only
+# against the name, otherwise it uses indexes for name and address.
+NOMINATIM_SEARCH_NAME_ONLY_THRESHOLD=500
+
+# Maximum number of OSM ids accepted by /lookup.
+NOMINATIM_LOOKUP_MAX_COUNT=50
+
+# Number of different geometry formats that may be queried in parallel.
+# Set to zero to disable polygon output.
+NOMINATIM_POLYGON_OUTPUT_MAX_TYPES=1
+
+### Log settings

 #
 #

-#// Number of different geometry formats that may be queried in parallel.
-#// Set to zero to disable polygon output.
-#@define('CONST_PolygonOutput_MaximumTypes', 1);
+# The following options allow to enable logging of API requests.
+# You must rerun 'nominatim refresh --website' after changing any of them.

 #
 #

-#// Log settings
-#// Set to true to log into new_query_log table.
-#// You should set up a cron job that regularly clears out this table.
-#@define('CONST_Log_DB', false);
-#// Set to a file name to enable logging to a file.
-#@define('CONST_Log_File', false);
+# Enable logging of requests into the DB.
+# The request will be logged into the new_query_log table.
+# You should set up a cron job that regularly clears out this table.
+NOMINATIM_LOG_DB=no
+
+# Enable logging of requests into a file.
+# To enable logging set this setting to the file to log to.
+NOMINATIM_LOG_FILE=