docs/admin/Update.md

   1 # Updating the Database
   2
   3 There are many different ways to update your Nominatim database.
   4 The following section describes how to keep it up-to-date using
   5 an [online replication service for OpenStreetMap data](https://wiki.openstreetmap.org/wiki/Planet.osm/diffs)
   6 For a list of other methods to add or update data see the output of
   7 `nominatim add-data --help`.
   8
   9 !!! important
  10     If you have configured a flatnode file for the import, then you
  11     need to keep this flatnode file around for updates.
  12
  13 ### Installing the newest version of Pyosmium
  14
  15 The replication process uses
  16 [Pyosmium](https://docs.osmcode.org/pyosmium/latest/updating_osm_data.html)
  17 to download update data from the server.
  18 It is recommended to install Pyosmium via pip.
  19 Run (as the same user who will later run the updates):
  20
  21 ```sh
  22 pip3 install --user osmium
  23 ```
  24
  25 ### Setting up the update process
  26
  27 Next the update process needs to be initialised. By default Nominatim is configured
  28 to update using the global minutely diffs.
  29
  30 If you want a different update source you will need to add some settings
  31 to `.env`. For example, to use the daily country extracts
  32 diffs for Ireland from Geofabrik add the following:
  33
  34     # base URL of the replication service
  35     NOMINATIM_REPLICATION_URL="https://download.geofabrik.de/europe/ireland-and-northern-ireland-updates"
  36     # How often upstream publishes diffs (in seconds)
  37     NOMINATIM_REPLICATION_UPDATE_INTERVAL=86400
  38     # How long to sleep if no update found yet (in seconds)
  39     NOMINATIM_REPLICATION_RECHECK_INTERVAL=900
  40
  41 To set up the update process now run the following command:
  42
  43     nominatim replication --init
  44
  45 It outputs the date where updates will start. Recheck that this date is
  46 what you expect.
  47
  48 The `replication --init` command needs to be rerun whenever the replication
  49 service is changed.
  50
  51 ### Updating Nominatim
  52
  53 Nominatim supports different modes how to retrieve the update data from the
  54 server. Which one you want to use depends on your exact setup and how often you
  55 want to retrieve updates.
  56
  57 These instructions are for using a single source of updates. If you have
  58 imported multiple country extracts and want to keep them
  59 up-to-date, [Advanced installations section](Advanced-Installations.md)
  60 contains instructions to set up and update multiple country extracts.
  61
  62 #### Continuous updates
  63
  64 This is the easiest mode. Simply run the replication command without any
  65 parameters:
  66
  67     nominatim replication
  68
  69 The update application keeps running forever and retrieves and applies
  70 new updates from the server as they are published.
  71
  72 You can run this command as a simple systemd service. Create a service
  73 description like that in `/etc/systemd/system/nominatim-updates.service`:
  74
  75 ```
  76 [Unit]
  77 Description=Continuous updates of Nominatim
  78
  79 [Service]
  80 WorkingDirectory=/srv/nominatim
  81 ExecStart=nominatim replication
  82 StandardOutput=append:/var/log/nominatim-updates.log
  83 StandardError=append:/var/log/nominatim-updates.error.log
  84 User=nominatim
  85 Group=nominatim
  86 Type=simple
  87
  88 [Install]
  89 WantedBy=multi-user.target
  90 ```
  91
  92 Replace the `WorkingDirectory` with your project directory. Also adapt user
  93 and group names as required.
  94
  95 Now activate the service and start the updates:
  96
  97 ```
  98 sudo systemctl daemon-reload
  99 sudo systemctl enable nominatim-updates
 100 sudo systemctl start nominatim-updates
 101 ```
 102
 103 #### One-time mode
 104
 105 When the `--once` parameter is given, then Nominatim will download exactly one
 106 batch of updates and then exit. This one-time mode still respects the
 107 `NOMINATIM_REPLICATION_UPDATE_INTERVAL` that you have set. If according to
 108 the update interval no new data has been published yet, it will go to sleep
 109 until the next expected update and only then attempt to download the next batch.
 110
 111 The one-time mode is particularly useful if you want to run updates continuously
 112 but need to schedule other work in between updates. For example, the main
 113 service at osm.org uses it, to regularly recompute postcodes -- a process that
 114 must not be run while updates are in progress. Its update script
 115 looks like this:
 116
 117 ```sh
 118 #!/bin/bash
 119
 120 # Switch to your project directory.
 121 cd /srv/nominatim
 122
 123 while true; do
 124   nominatim replication --once
 125   if [ -f "/srv/nominatim/schedule-maintenance" ]; then
 126     rm /srv/nominatim/schedule-maintenance
 127     nominatim refresh --postcodes
 128   fi
 129 done
 130 ```
 131
 132 A cron job then creates the file `/srv/nominatim/schedule-maintenance` once per night.
 133
 134 ##### One-time mode with systemd
 135
 136 You can run the one-time mode with a systemd timer & service.
 137
 138 Create a timer description like `/etc/systemd/system/nominatim-updates.timer`:
 139
 140 ```
 141 [Unit]
 142 Description=Timer to start updates of Nominatim
 143
 144 [Timer]
 145 OnActiveSec=2
 146 OnUnitActiveSec=1min
 147 Unit=nominatim-updates.service
 148
 149 [Install]
 150 WantedBy=multi-user.target
 151 ```
 152
 153 And then a similar service definition: `/etc/systemd/system/nominatim-updates.service`:
 154
 155 ```
 156 [Unit]
 157 Description=Single updates of Nominatim
 158
 159 [Service]
 160 WorkingDirectory=/srv/nominatim
 161 ExecStart=nominatim replication --once
 162 StandardOutput=append:/var/log/nominatim-updates.log
 163 StandardError=append:/var/log/nominatim-updates.error.log
 164 User=nominatim
 165 Group=nominatim
 166 Type=simple
 167
 168 [Install]
 169 WantedBy=multi-user.target
 170 ```
 171
 172 Replace the `WorkingDirectory` with your project directory. Also adapt user and
 173 group names as required. `OnUnitActiveSec` defines how often the individual
 174 update command is run.
 175
 176 Now activate the service and start the updates:
 177
 178 ```
 179 sudo systemctl daemon-reload
 180 sudo systemctl enable nominatim-updates.timer
 181 sudo systemctl start nominatim-updates.timer
 182 ```
 183
 184 You can stop future data updates, while allowing any current, in-progress
 185 update steps to finish, by running `sudo systemctl stop
 186 nominatim-updates.timer` and waiting until `nominatim-updates.service` isn't
 187 running (`sudo systemctl is-active nominatim-updates.service`). Current output
 188 from the update can be seen like above (`systemctl status
 189 nominatim-updates.service`).
 190
 191
 192 #### Catch-up mode
 193
 194 With the `--catch-up` parameter, Nominatim will immediately try to download
 195 all changes from the server until the database is up-to-date. The catch-up mode
 196 still respects the parameter `NOMINATIM_REPLICATION_MAX_DIFF`. It downloads and
 197 applies the changes in appropriate batches until all is done.
 198
 199 The catch-up mode is foremost useful to bring the database up to speed after the
 200 initial import. Give that the service usually is not in production at this
 201 point, you can temporarily be a bit more generous with the batch size and
 202 number of threads you use for the updates by running catch-up like this:
 203
 204 ```
 205 cd /srv/nominatim
 206 NOMINATIM_REPLICATION_MAX_DIFF=5000 nominatim replication --catch-up --threads 15
 207 ```
 208
 209 The catch-up mode is also useful when you want to apply updates at a lower
 210 frequency than what the source publishes. You can set up a cron job to run
 211 replication catch-up at whatever interval you desire.
 212
 213 !!! hint
 214     When running scheduled updates with catch-up, it is a good idea to choose
 215     a replication source with an update frequency that is an order of magnitude
 216     lower. For example, if you want to update once a day, use an hourly updated
 217     source. This makes sure that you don't miss an entire day of updates when
 218     the source is unexpectedly late to publish its update.
 219
 220     If you want to use the source with the same update frequency (e.g. a daily
 221     updated source with daily updates), use the
 222     continuous update mode. It ensures to re-request the newest update until it
 223     is published.