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 #### One-time mode
  63
  64 When the `--once` parameter is given, then Nominatim will download exactly one
  65 batch of updates and then exit. This one-time mode still respects the
  66 `NOMINATIM_REPLICATION_UPDATE_INTERVAL` that you have set. If according to
  67 the update interval no new data has been published yet, it will go to sleep
  68 until the next expected update and only then attempt to download the next batch.
  69
  70 The one-time mode is particularly useful if you want to run updates continuously
  71 but need to schedule other work in between updates. For example, the main
  72 service at osm.org uses it, to regularly recompute postcodes -- a process that
  73 must not be run while updates are in progress. Its update script
  74 looks like this:
  75
  76 ```sh
  77 #!/bin/bash
  78
  79 # Switch to your project directory.
  80 cd /srv/nominatim
  81
  82 while true; do
  83   nominatim replication --once
  84   if [ -f "/srv/nominatim/schedule-maintenance" ]; then
  85     rm /srv/nominatim/schedule-maintenance
  86     nominatim refresh --postcodes
  87   fi
  88 done
  89 ```
  90
  91 A cron job then creates the file `/srv/nominatim/schedule-maintenance` once per night.
  92
  93 ##### One-time mode with systemd
  94
  95 You can run the one-time mode with a systemd timer & service.
  96
  97 Create a timer description like `/etc/systemd/system/nominatim-updates.timer`:
  98
  99 ```
 100 [Unit]
 101 Description=Timer to start updates of Nominatim
 102
 103 [Timer]
 104 OnActiveSec=2
 105 OnUnitActiveSec=1min
 106 Unit=nominatim-updates.service
 107
 108 [Install]
 109 WantedBy=multi-user.target
 110 ```
 111
 112 And then a similar service definition: `/etc/systemd/system/nominatim-updates.service`:
 113
 114 ```
 115 [Unit]
 116 Description=Single updates of Nominatim
 117
 118 [Service]
 119 WorkingDirectory=/srv/nominatim
 120 ExecStart=nominatim replication --once
 121 StandardOutput=append:/var/log/nominatim-updates.log
 122 StandardError=append:/var/log/nominatim-updates.error.log
 123 User=nominatim
 124 Group=nominatim
 125 Type=simple
 126
 127 [Install]
 128 WantedBy=multi-user.target
 129 ```
 130
 131 Replace the `WorkingDirectory` with your project directory. Also adapt user and
 132 group names as required. `OnUnitActiveSec` defines how often the individual
 133 update command is run.
 134
 135 Now activate the service and start the updates:
 136
 137 ```
 138 sudo systemctl daemon-reload
 139 sudo systemctl enable nominatim-updates.timer
 140 sudo systemctl start nominatim-updates.timer
 141 ```
 142
 143 You can stop future data updates, while allowing any current, in-progress
 144 update steps to finish, by running `sudo systemctl stop
 145 nominatim-updates.timer` and waiting until `nominatim-updates.service` isn't
 146 running (`sudo systemctl is-active nominatim-updates.service`). Current output
 147 from the update can be seen like above (`systemctl status
 148 nominatim-updates.service`).
 149
 150
 151 #### Catch-up mode
 152
 153 With the `--catch-up` parameter, Nominatim will immediately try to download
 154 all changes from the server until the database is up-to-date. The catch-up mode
 155 still respects the parameter `NOMINATIM_REPLICATION_MAX_DIFF`. It downloads and
 156 applies the changes in appropriate batches until all is done.
 157
 158 The catch-up mode is foremost useful to bring the database up to speed after the
 159 initial import. Give that the service usually is not in production at this
 160 point, you can temporarily be a bit more generous with the batch size and
 161 number of threads you use for the updates by running catch-up like this:
 162
 163 ```
 164 cd /srv/nominatim
 165 NOMINATIM_REPLICATION_MAX_DIFF=5000 nominatim replication --catch-up --threads 15
 166 ```
 167
 168 The catch-up mode is also useful when you want to apply updates at a lower
 169 frequency than what the source publishes. You can set up a cron job to run
 170 replication catch-up at whatever interval you desire.
 171
 172 !!! hint
 173     When running scheduled updates with catch-up, it is a good idea to choose
 174     a replication source with an update frequency that is an order of magnitude
 175     lower. For example, if you want to update once a day, use an hourly updated
 176     source. This makes sure that you don't miss an entire day of updates when
 177     the source is unexpectedly late to publish its update.
 178
 179     If you want to use the source with the same update frequency (e.g. a daily
 180     updated source with daily updates), use the
 181     continuous update mode. It ensures to re-request the newest update until it
 182     is published.
 183
 184
 185 #### Continuous updates
 186
 187 !!! danger
 188     This mode is no longer recommended to use and will removed in future
 189     releases. systemd is much better
 190     suited for running regular updates. Please refer to the setup
 191     instructions for running one-time mode with systemd above.
 192
 193 This is the easiest mode. Simply run the replication command without any
 194 parameters:
 195
 196     nominatim replication
 197
 198 The update application keeps running forever and retrieves and applies
 199 new updates from the server as they are published.
 200
 201 You can run this command as a simple systemd service. Create a service
 202 description like that in `/etc/systemd/system/nominatim-updates.service`:
 203
 204 ```
 205 [Unit]
 206 Description=Continuous updates of Nominatim
 207
 208 [Service]
 209 WorkingDirectory=/srv/nominatim
 210 ExecStart=nominatim replication
 211 StandardOutput=append:/var/log/nominatim-updates.log
 212 StandardError=append:/var/log/nominatim-updates.error.log
 213 User=nominatim
 214 Group=nominatim
 215 Type=simple
 216
 217 [Install]
 218 WantedBy=multi-user.target
 219 ```
 220
 221 Replace the `WorkingDirectory` with your project directory. Also adapt user
 222 and group names as required.
 223
 224 Now activate the service and start the updates:
 225
 226 ```
 227 sudo systemctl daemon-reload
 228 sudo systemctl enable nominatim-updates
 229 sudo systemctl start nominatim-updates
 230 ```
 231
 232