From e7b738fe35a2ec13efdc22c9f068c477182da6c3 Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Thu, 23 Aug 2018 23:12:10 +0200 Subject: [PATCH] cleanup documentation Remove level 3 (page title) from TOC and add permalinks. Also fix and update some minor stuff in the docs. --- docs/CMakeLists.txt | 1 + docs/admin/Faq.md | 68 ++++++++++++++++++--------------- docs/admin/Import-and-Update.md | 26 +++++++------ docs/admin/Installation.md | 22 ++++++----- docs/admin/Migration.md | 16 ++++++-- docs/extra.css | 3 ++ docs/mkdocs.yml | 3 ++ 7 files changed, 83 insertions(+), 56 deletions(-) create mode 100644 docs/extra.css diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index f335060f..f50b38ab 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -11,6 +11,7 @@ ADD_CUSTOM_TARGET(doc COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/develop ${CMAKE_CURRENT_BINARY_DIR}/develop COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/api ${CMAKE_CURRENT_BINARY_DIR}/api COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/index.md ${CMAKE_CURRENT_BINARY_DIR}/index.md + COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/extra.css ${CMAKE_CURRENT_BINARY_DIR}/extra.css COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Centos-7.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Centos-7.md COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Ubuntu-16.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Ubuntu-16.md COMMAND mkdocs build -d ${CMAKE_CURRENT_BINARY_DIR}/../site-html -f ${CMAKE_CURRENT_BINARY_DIR}/../mkdocs.yml diff --git a/docs/admin/Faq.md b/docs/admin/Faq.md index f3ad670a..46da7e21 100644 --- a/docs/admin/Faq.md +++ b/docs/admin/Faq.md @@ -1,33 +1,6 @@ -# Running Your Own Instance - -### Can I import multiple countries and keep them up to date? - -You should use the extracts and updates from https://download.geofabrik.de. -For the initial import, download the countries you need and merge them. -See [OSM Help](https://help.openstreetmap.org/questions/48843/merging-two-or-more-geographical-areas-to-import-two-or-more-osm-files-in-nominatim) -for examples how to do that. Use the resulting single osm file when -running `setup.php`. - -For updates you need to download the change files for each country -once per day and apply them **separately** using - - ./utils/update.php --import-diff --index - -See [this issue](https://github.com/openstreetmap/Nominatim/issues/60#issuecomment-18679446) -for a script that runs the updates using osmosis. - -### Can I import negative OSM ids into Nominatim? - -See [https://help.openstreetmap.org/questions/64662/nominatim-flatnode-with-negative-id]() - -### Missing XML or text declaration - -The website might show: `XML Parsing Error: XML or text declaration not at start of entity Location.` - -Make sure there are no spaces at the beginning of your `settings/local.php` file. +# Troubleshooting Nominatim Installations - -# Installation +## Installation Issues ### Can a stopped/killed import process be resumed? @@ -145,9 +118,9 @@ Example error message CONTEXT: PL/pgSQL function make_standard_name(text) line 5 at assignment] ``` -The user the webserver, e.g. Apache, runs under needs to have access to that file. Same for the user the Postgres runs as. You can find the user like [this](https://serverfault.com/questions/125865/finding-out-what-user-apache-is-running-as), for default Ubuntu operating system for example it's `www-data`. +The Postgresql database, i.e. user postgres, needs to have access to that file. -The permission need to be read&executable by everybody, e.g. +The permission need to be read & executable by everybody, e.g. ``` -rwxr-xr-x 1 nominatim nominatim 297984 build/module/nominatim.so @@ -155,6 +128,9 @@ The permission need to be read&executable by everybody, e.g. Try `chmod a+r nominatim.so; chmod a+x nominatim.so`. +When running SELinux, make sure that the +[context is set up correctly](../appendix/Install-on-Centos-7/#adding-selinux-security-settings). + ### Setup.php fails with "DB Error: extension not found" Make sure you have the Postgres extensions hstore and postgis installed. @@ -177,3 +153,33 @@ That's fine. For each import the flatnodes file get overwritten. See [https://help.openstreetmap.org/questions/52419/nominatim-flatnode-storage]() for more information. + +## Running your own instance + +### Can I import multiple countries and keep them up to date? + +You should use the extracts and updates from https://download.geofabrik.de. +For the initial import, download the countries you need and merge them. +See [OSM Help](https://help.openstreetmap.org/questions/48843/merging-two-or-more-geographical-areas-to-import-two-or-more-osm-files-in-nominatim) +for examples how to do that. Use the resulting single osm file when +running `setup.php`. + +For updates you need to download the change files for each country +once per day and apply them **separately** using + + ./utils/update.php --import-diff --index + +See [this issue](https://github.com/openstreetmap/Nominatim/issues/60#issuecomment-18679446) +for a script that runs the updates using osmosis. + +### Can I import negative OSM ids into Nominatim? + +See [this question of Stackoverflow](https://help.openstreetmap.org/questions/64662/nominatim-flatnode-with-negative-id). + +### Missing XML or text declaration + +The website might show: `XML Parsing Error: XML or text declaration not at start of entity Location.` + +Make sure there are no spaces at the beginning of your `settings/local.php` file. + + diff --git a/docs/admin/Import-and-Update.md b/docs/admin/Import-and-Update.md index 25954ba0..731ff8fa 100644 --- a/docs/admin/Import-and-Update.md +++ b/docs/admin/Import-and-Update.md @@ -1,9 +1,11 @@ +# Importing and Updating the Database + The following instructions explain how to create a Nominatim database from an OSM planet file and how to keep the database up to date. It is assumed that you have already successfully installed the Nominatim software itself, if not return to the [installation page](Installation.md). -# Configuration setup in settings/local.php +## Configuration setup in settings/local.php The Nominatim server can be customized via the file `settings/local.php` in the build directory. Note that this is a PHP file, so it must always @@ -16,7 +18,7 @@ without any leading spaces. There are lots of configuration settings you can tweak. Have a look at `settings/default.php` for a full list. Most should have a sensible default. -### Flatnode files +#### Flatnode files If you plan to import a large dataset (e.g. Europe, North America, planet), you should also enable flatnode storage of node locations. With this @@ -29,9 +31,9 @@ Add to your `settings/local.php`: Replace the second part with a suitable path on your system and make sure the directory exists. There should be at least 40GB of free space. -# Downloading additional data +## Downloading additional data -## Wikipedia rankings +### Wikipedia rankings Wikipedia can be used as an optional auxiliary data source to help indicate the importance of osm features. Nominatim will work without this information @@ -49,7 +51,7 @@ size of nominatim. They also increase the install time by an hour or so. the initial import of the data if you want the rankings applied to the loaded data. -## UK postcodes +### UK postcodes Nominatim can use postcodes from an external source to improve searches that involve a UK postcode. This data can be optionally downloaded: @@ -57,7 +59,7 @@ Nominatim can use postcodes from an external source to improve searches that inv wget https://www.nominatim.org/data/gb_postcode_data.sql.gz -# Initial import of the data +## Initial import of the data **Important:** first try the import with a small excerpt, for example from [Geofabrik](https://download.geofabrik.de). @@ -97,7 +99,7 @@ you also need to enable these key phrases like this: Note that this command downloads the phrases from the wiki link above. -# Installing Tiger housenumber data for the US +## Installing Tiger housenumber data for the US Nominatim is able to use the official TIGER address set to complement the OSM house number data in the US. You can add TIGER data to your own Nominatim @@ -146,13 +148,13 @@ SQL files, Nominatim needs for the import: Be warned that this can take quite a long time. After this process is finished, the same preprocessed files as above are available in `data/tiger`. -# Updates +## Updates There are many different possibilities to update your Nominatim database. The following section describes how to keep it up-to-date with Pyosmium. For a list of other methods see the output of `./utils/update.php --help`. -### Installing the newest version of Pyosmium +#### Installing the newest version of Pyosmium It is recommended to install Pyosmium via pip. Run (as the same user who will later run the updates): @@ -161,7 +163,7 @@ will later run the updates): pip install --user osmium ``` -Nominatim needs a tool called `pyosmium-get-updates` that comes with +Nominatim needs a tool called `pyosmium-get-updates`, which comes with Pyosmium. You need to tell Nominatim where to find it. Add the following line to your `settings/local.php`: @@ -170,7 +172,7 @@ following line to your `settings/local.php`: The path above is fine if you used the `--user` parameter with pip. Replace `user` with your user name. -### Setting up the update process +#### Setting up the update process Next the update needs to be initialised. By default Nominatim is configured to update using the global minutely diffs. @@ -196,7 +198,7 @@ what you expect. The --init-updates command needs to be rerun whenever the replication service is changed. -### Updating Nominatim +#### Updating Nominatim The following command will keep your database constantly up to date: diff --git a/docs/admin/Installation.md b/docs/admin/Installation.md index 67c4fe3c..3d276c06 100644 --- a/docs/admin/Installation.md +++ b/docs/admin/Installation.md @@ -1,3 +1,5 @@ +# Basic Installation + This page contains generic installation instructions for Nominatim and its prerequisites. There are also step-by-step instructions available for the following operating systems: @@ -15,9 +17,9 @@ and can't offer support. * [Docker on Kubernetes](https://github.com/peter-evans/nominatim-k8s) * [Ansible](https://github.com/synthesio/infra-ansible-nominatim) -# Prerequisites +## Prerequisites -## Software +### Software For compiling: @@ -49,22 +51,22 @@ For running continuous updates: * [pyosmium](http://osmcode.org/pyosmium/) -## Hardware +### Hardware A minimum of 2GB of RAM is required or installation will fail. For a full planet import 32GB of RAM or more strongly are recommended. -For a full planet install you will need about 600GB of hard disk space (as of -January 2017, take into account that the OSM database is growing fast). SSD disks +For a full planet install you will need at least 700GB of hard disk space +(take into account that the OSM database is growing fast). SSD disks will help considerably to speed up import and queries. On a 6-core machine with 32GB RAM and SSDs the import of a full planet takes a bit more than 2 days. Without SSDs 7-8 days are more realistic. -# Setup of the server +## Setup of the server -## PostgreSQL tuning +### PostgreSQL tuning You might want to tune your PostgreSQL installation so that the later steps make best use of your hardware. You should tune the following parameters in @@ -91,13 +93,13 @@ Don't forget to reenable them after the initial import or you risk database corruption. Autovacuum must not be switched off because it ensures that the tables are frequently analysed. -## Webserver setup +### Webserver setup The `website/` directory in the build directory contains the configured website. Include the directory into your webbrowser to serve php files from there. -### Configure for use with Apache +#### Configure for use with Apache Make sure your Apache configuration contains the required permissions for the directory and create an alias: @@ -116,7 +118,7 @@ build directory. After making changes in the apache config you need to restart apache. The website should now be available on http://localhost/nominatim. -### Configure for use with Nginx +#### Configure for use with Nginx Use php-fpm as a deamon for serving PHP cgi. Install php-fpm together with nginx. diff --git a/docs/admin/Migration.md b/docs/admin/Migration.md index 2f03c200..0a522488 100644 --- a/docs/admin/Migration.md +++ b/docs/admin/Migration.md @@ -1,5 +1,4 @@ -Database Migrations -=================== +# Database Migrations This page describes database migrations necessary to update existing databases to newer versions of Nominatim. @@ -7,7 +6,7 @@ to newer versions of Nominatim. SQL statements should be executed from the postgres commandline. Execute `psql nominiatim` to enter command line mode. -# 3.0.0 -> 3.1.0 +## 3.0.0 -> 3.1.0 ### Postcode Table @@ -26,6 +25,17 @@ CREATE INDEX idx_postcode_geometry ON location_postcode USING GIST (geometry); CREATE UNIQUE INDEX idx_postcode_id ON location_postcode USING BTREE (place_id); CREATE INDEX idx_postcode_postcode ON location_postcode USING BTREE (postcode); GRANT SELECT ON location_postcode TO "www-data"; +drop type if exists nearfeaturecentr cascade; +create type nearfeaturecentr as ( + place_id BIGINT, + keywords int[], + rank_address smallint, + rank_search smallint, + distance float, + isguess boolean, + postcode TEXT, + centroid GEOMETRY +); ``` Add postcode column to `location_area` tables with SQL statement: diff --git a/docs/extra.css b/docs/extra.css new file mode 100644 index 00000000..a8c3a1c8 --- /dev/null +++ b/docs/extra.css @@ -0,0 +1,3 @@ +.toctree-l3 { + display: none!important +} diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 7c3cd895..219176f6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -26,3 +26,6 @@ pages: markdown_extensions: - codehilite: use_pygments: False + - toc: + permalink:  +extra_css: [extra.css] -- 2.45.1