up-to-date, [Advanced installations section](Advanced-Installations.md)
contains instructions to set up and update multiple country extracts.
-#### Continuous updates
+#### One-time mode
-This is the easiest mode. Simply run the replication command without any
-parameters:
+When the `--once` parameter is given, then Nominatim will download exactly one
+batch of updates and then exit. This one-time mode still respects the
+`NOMINATIM_REPLICATION_UPDATE_INTERVAL` that you have set. If according to
+the update interval no new data has been published yet, it will go to sleep
+until the next expected update and only then attempt to download the next batch.
- nominatim replication
+The one-time mode is particularly useful if you want to run updates continuously
+but need to schedule other work in between updates. For example, you might
+want to regularly recompute postcodes -- a process that
+must not be run while updates are in progress. An update script refreshing
+postcodes regularly might look like this:
-The update application keeps running forever and retrieves and applies
-new updates from the server as they are published.
+```sh
+#!/bin/bash
-You can run this command as a simple systemd service. Create a service
-description like that in `/etc/systemd/system/nominatim-update.service`:
+# Switch to your project directory.
+cd /srv/nominatim
+
+while true; do
+ nominatim replication --once
+ if [ -f "/srv/nominatim/schedule-maintenance" ]; then
+ rm /srv/nominatim/schedule-maintenance
+ nominatim refresh --postcodes
+ fi
+done
+```
+
+A cron job then creates the file `/srv/nominatim/schedule-maintenance` once per night.
+
+##### One-time mode with systemd
+
+You can run the one-time mode with a systemd timer & service.
+
+Create a timer description like `/etc/systemd/system/nominatim-updates.timer`:
```
[Unit]
-Description=Continuous updates of Nominatim
+Description=Timer to start updates of Nominatim
+
+[Timer]
+OnActiveSec=2
+OnUnitActiveSec=1min
+Unit=nominatim-updates.service
+
+[Install]
+WantedBy=multi-user.target
+```
+
+`OnUnitActiveSec` defines how often the individual update command is run.
+
+Then add a service definition for the timer in `/etc/systemd/system/nominatim-updates.service`:
+
+```
+[Unit]
+Description=Single updates of Nominatim
[Service]
-WorkingDirectory=/srv/nominatim
-ExecStart=nominatim replication
-StandardOutput=append:/var/log/nominatim-updates.log
-StandardError=append:/var/log/nominatim-updates.error.log
+WorkingDirectory=/srv/nominatim-project
+ExecStart=/srv/nominatim-venv/bin/nominatim replication --once
+StandardOutput=journald
+StandardError=inherit
User=nominatim
Group=nominatim
Type=simple
WantedBy=multi-user.target
```
-Replace the `WorkingDirectory` with your project directory. Also adapt user
-and group names as required.
+Replace the `WorkingDirectory` with your project directory. `ExecStart` points
+to the nominatim binary that was installed in your virtualenv earlier.
+Finally, you might need to adapt user and group names as required.
Now activate the service and start the updates:
```
sudo systemctl daemon-reload
-sudo systemctl enable nominatim-updates
-sudo systemctl start nominatim-updates
+sudo systemctl enable nominatim-updates.timer
+sudo systemctl start nominatim-updates.timer
```
-#### One-time mode
-
-When the `--once` parameter is given, then Nominatim will download exactly one
-batch of updates and then exit. This one-time mode still respects the
-`NOMINATIM_REPLICATION_UPDATE_INTERVAL` that you have set. If according to
-the update interval no new data has been published yet, it will go to sleep
-until the next expected update and only then attempt to download the next batch.
-
-The one-time mode is particularly useful if you want to run updates continuously
-but need to schedule other work in between updates. For example, the main
-service at osm.org uses it, to regularly recompute postcodes -- a process that
-must not be run while updates are in progress. Its update script
-looks like this:
-
-```sh
-#!/bin/bash
-
-# Switch to your project directory.
-cd /srv/nominatim
-
-while true; do
- nominatim replication --once
- if [ -f "/srv/nominatim/schedule-mainenance" ]; then
- rm /srv/nominatim/schedule-mainenance
- nominatim refresh --postcodes
- fi
-done
-```
+You can stop future data updates while allowing any current, in-progress
+update steps to finish, by running `sudo systemctl stop
+nominatim-updates.timer` and waiting until `nominatim-updates.service` isn't
+running (`sudo systemctl is-active nominatim-updates.service`).
-A cron job then creates the file `/srv/nominatim/need-mainenance` once per night.
+To check the output from the update process, use journalctl: `journalctl -u
+nominatim-updates.service`
#### Catch-up mode
still respects the parameter `NOMINATIM_REPLICATION_MAX_DIFF`. It downloads and
applies the changes in appropriate batches until all is done.
-The catch-up mode is foremost useful to bring the database up to speed after the
+The catch-up mode is foremost useful to bring the database up to date after the
initial import. Give that the service usually is not in production at this
point, you can temporarily be a bit more generous with the batch size and
number of threads you use for the updates by running catch-up like this:
```
-cd /srv/nominatim
+cd /srv/nominatim-project
NOMINATIM_REPLICATION_MAX_DIFF=5000 nominatim replication --catch-up --threads 15
```
When running scheduled updates with catch-up, it is a good idea to choose
a replication source with an update frequency that is an order of magnitude
lower. For example, if you want to update once a day, use an hourly updated
- source. This makes sure that you don't miss an entire day of updates when
- the source is unexpectely late to publish its update.
+ source. This ensures that you don't miss an entire day of updates when
+ the source is unexpectedly late to publish its update.
If you want to use the source with the same update frequency (e.g. a daily
updated source with daily updates), use the
- continuous update mode. It ensures to re-request the newest update until it
- is published.
+ once mode together with a frequently run systemd script as described above.
+ It ensures to re-request the newest update until they have been published.
+
+
+#### Continuous updates
+
+!!! danger
+ This mode is no longer recommended to use and will removed in future
+ releases. systemd is much better
+ suited for running regular updates. Please refer to the setup
+ instructions for running one-time mode with systemd above.
+
+This is the easiest mode. Simply run the replication command without any
+parameters:
+
+ nominatim replication
+
+The update application keeps running forever and retrieves and applies
+new updates from the server as they are published.
projects / nominatim.git / blobdiff