Створення тайлового сервера вручну (Debian 12)⚓︎

На цій сторінці міститься опис зі встановлення, розгортання та налаштування всього потрібного програмного забезпечення для роботи вашого тайлового сервера. Покрокові інструкції описують встановлення тайлового сервера на Debian Linux 12 (bookworm), вони були перевірені у липні 2023.

Встановлення програмного забезпечення⚓︎

Тайловий сервер OpenStreetMap – це набір програмного забезпечення та бібліотек, які працюють разом генеруючи тайли. Як це трапляється доволі часто в OpenStreetMap, існує кілька різних шляхів для досягнення мети та майже кожен компонент має альтернативу, з власними недоліками та перевагами. Цей посібник описує найбільш стандартну версію, що схожа на те, що використовується головним тайловим сервером OpenStreetMap.

Тайловий сервер складається з пʼяти головних частин: mod_tile, renderd, mapnik, osm2pgsql та база даних postgresql/postgis. Mod_tile – модуль сервера Apache, який обслуговує тайловий кеш та визначає які тайли потрібно перегенерувати, через їх відсутність у кеші або тому, що вони застаріли. Renderd визначає пріоритети в чергах різного штибу запитів для згладжування навантаження. Mapnik – бібліотека, яка відповідає безпосередньо за створення тайлів з черги, якою керує renderd.

Зауважте, що це керівництво було написане та протестоване з використанням нововстановленого сервера з операційною системою Debian 12. Якщо у вас встановлені інші версії програмного забезпечення (можливо ви оновились з попередньої версії Ubuntu, або у вас підʼєднані інші репозиторії PPA), можливо вам доведеться внести певні зміни.

Для того, щоб створити всі ці компоненти, вам спочатку треба встановити наступні залежності.

Debian з типовими налаштуваннями не містить встановленої утиліти sudo, тож нам доведеться скористуватись правами користувача root, щоб додати її та інші потрібні нам компоненти:

su -
apt install \
    sudo screen locate libapache2-mod-tile \
    renderd git tar unzip wget bzip2 apache2 \
    lua5.1 mapnik-utils python3-mapnik \
    python3-psycopg2 python3-yaml gdal-bin \
    node-carto postgresql postgresql-contrib \
    postgis postgresql-15-postgis-3 \
    postgresql-15-postgis-3-scripts osm2pgsql \
    net-tools curl

Перебуваючи в оточені root перевіримо, чи ми можемо використовувати утиліту sudo в оточені нашого звичайного користувача. Замініть youruseraccount на ваш обліковий запис в системі. Не намагайтесь та не робіть все в оточені root; система не буде працювати.

usermod -aG sudo youruseraccount
exit

Повернувшись в оточення звичайного користувача виконайте вихід та вхід до вашого оточення, після чого перевірите роботу утиліти "sudo":

sudo whoami

У відповідь ви маєте отримати root.

На цьому етапі було додано кілька нових облікових записів. Ви можете ознайомитись з ними за допомогою tail /etc/passwd. postgres – використовується для керування базами даних, які ми будемо використовувати для збереження даних потрібних нам для рендерингу. _renderd – використовується фоновою службою renderd, і нам далі доведеться переконатись, що більшість команд запускаються саме цим обліковим записом.

Тепер вам треба створити базу даних postgis. Типові налаштування різноманітних програм очікують що база даних називатиметься gis, тож ми будемо дотримуватись цієї угоди в цім керівництві, хоча це й не обовʼязково. Зверніть увагу, що _renderd нижче збігається з іменем користувача, який використовується для фонової служби renderd.

sudo -u postgres -i
createuser _renderd
createdb -E UTF8 -O _renderd gis

Поки ви працюєте як користувач postgres, встановіть PostGIS в базу даних PostgreSQL:

psql

(це призведе до появи postgres=# на початку рядка консолі)

\c gis

(у відповідь ви побачите: "You are now connected to database 'gis' as user 'postgres'"
["Тепер ви підʼєднані до бази даних 'gis' як користувач 'postgres'"])

CREATE EXTENSION postgis;

(у відповідь ви побачите: CREATE EXTENSION)

CREATE EXTENSION hstore;

(у відповідь ви побачите: CREATE EXTENSION)

ALTER TABLE geometry_columns OWNER TO _renderd;

(у відповідь ви побачите: ALTER TABLE)

ALTER TABLE spatial_ref_sys OWNER TO _renderd;

(у відповідь ви побачите: ALTER TABLE)

\q

(це призведе до виходу з сесії psql та повернення назад у консоль Linux)

exit

(повернення назад до сесії користувача, в якій ми знаходились до виконання команди sudo -u postgres -i вище)

Mapnik⚓︎

Mapnik ми встановили раніше, разом із "sudo", перевіримо чи він працює:

python3
>>> import mapnik
>>>

Якщо python у відповідь видає тільки >>> без повідомлення про помилки, значить бібліотека Mapnik є доступною в Python. Вітаємо! Для виходу із сесії Python скористайтесь наступною командою:

>>> quit()

Налаштування стилів⚓︎

Тепер, після того, як все потрібне програмне забезпечення встановлене, вам треба завантажити та налаштувати стилі.

Стиль, який ми будемо використовувати, – це стиль який застосовується для створення "Стандартного" шару на сайті openstreetmap.org. Ми обрали його через гарну документацію і те, що він здатен працювати для будь-якої частини світу, навіть там де не використовується латинка. Але у нього є й певні недоліки – це компромісні рішення для того, щоб працювати в глобальних масштабах, він дуже складний для розуміння та внесення змін, якщо вам доведеться їх вносити.

Код стилю "OpenStreetMap Carto" з вебсайту openstreetmap.org знаходиться на GitHub – https://github.com/gravitystorm/openstreetmap-carto/ та також має власні інструкції зі встановлення – https://github.com/gravitystorm/openstreetmap-carto/blob/master/INSTALL.md. Про те, що потрібно зробити, ми розповімо тут.

Передбачається що ми розміщуємо стиль в теці ~/src домашньої директорії звичайного користувача (не root):

mkdir ~/src
cd ~/src
git clone https://github.com/gravitystorm/openstreetmap-carto
cd openstreetmap-carto
git pull --all
git switch --detach v5.9.0

"git switch" потрібно виконати тому, що це остання версія, яку ви можете побачити на OpenStreetMap, але OSM Carto перебуває у процесі переходу на інший формат бази даних. Дивіться [INSTALL.md] (https://github.com/gravitystorm/openstreetmap-carto/blob/master/INSTALL.md) для отримання нової версії OSM Carto.

Далі, перевіримо чи в наявності у нас потрібна версія компілятора carto.

carto -v

У відповідь ми маємо отримати інформацію про номер версії, яка має бути не менше ніж:

1.2.0

Після цього ми перетворимо проєкт carto у зрозумілий для Mapnik вигляд:

carto project.mml > mapnik.xml

Тепер у нас є стиль Mapnik XML – /home/youraccountname/src/openstreetmap-carto/mapnik.xml.

Завантаження даних⚓︎

Для початку, завантажимо невеличку частину тестових даних. Серед різномаїття місць для отримання даних, оберемо download.geofabrik.de, що містить великий перелік різних варіантів для завантаження. Візьмімо для прикладу Азербайджан (~32.4 Мб).

Перейдіть за посиланням https://download.geofabrik.de/asia/azerbaijan.html та зверніть увагу на дату "This file was last modified" (щось схоже на "2020-11-13T21:42:03Z"). Вона нам знадобиться потім, коли у нас виникне потреба оновити наші дані даними, які учасники OpenStreetMap додали з моменту нашого імпорту. Завантажимо дані:

mkdir ~/data
cd ~/data
wget https://download.geofabrik.de/asia/azerbaijan-latest.osm.pbf

Далі нам треба переконатись, що обліковий запис _renderd має доступ до стилю. Йому потрібен доступ до всього, що ви завантажили для нього, але, типово, він не повинен мати доступу до вашої домашньої теки. Якщо ми передбачаємо використовувати теку src, що знаходиться в середині теки вашого облікового запису, для цього перейдіть до неї та виконайте команду

chmod o+rx ~

Якщо ви не бажаєте робити цього, ви можете перемістити стиль в інше місце та змінити посилання на розташування файлів у наступних командах.

Наступна команда допоможе вам перенести завантажені дані до вашої бази даних. На цьому етапі зросте навантаження на дискові операції через потребу перенесення значного обсягу інформації; імпорт всієї планети може тривати кілька годин, днів та навіть тижнів, в залежності від потужностей вашого серверного обладнання. Зрозуміло, що для невеликих частин даних імпорт відбувається значно швидше, можливо вам доведеться поекспериментувати зі значенням параметра -C, щоб вкластись у наявну оперативну памʼять вашого сервера. Зверніть увагу, що ми робимо це в оточені користувача _renderd.

sudo -u _renderd osm2pgsql \
    -d gis --create --slim  -G --hstore \
    --tag-transform-script \
        ~/src/openstreetmap-carto/openstreetmap-carto.lua \
    -C 2500 --number-processes 1 \
    -S ~/src/openstreetmap-carto/openstreetmap-carto.style \
    ~/data/azerbaijan-latest.osm.pbf

Розберімося що означають всі ці параметри:

-d gis: База даних, з якою ми працюємо (типово використовується gis; тут треба вказати її явно).
--create: Завантажити дані в пусту базу даних, замість спроб додати їх до наявних.
--slim: osm2pgsql може використовувати різноманітні схеми таблиць; slim годиться для генерації тайлів.
-G: Визначає, яким чином будуть оброблятись мультиполігони.
--hstore: Дозволяє використовувати для генерації тайлів теґи, для яких немає окремих стовпців в базі даних.
--tag-transform-script ~/src/openstreetmap-carto/openstreetmap-carto.lua: Визначає скрипт lua, який використовується для обробки теґів. Це простий спосіб обробки теґів OSM до того, як вони будуть використані в стилі, що спрощує логіку самого стилю.
-C 2500: Виділяє 2.5 Гб оперативної памʼяті для osm2pgsql на виконання імпорту. Якщо у вас менше оперативної памʼяті, спробуйте менше значення. Якщо процес імпорту буде знищений через нестачу оперативної памʼяті, спробуйте зменшити це число або використовуйте менший обсяг даних.
--number-processes 1: Використовувати одне ядро процесора. Якщо у вас багатоядерний процесор можете використовувати більшу кількість ядер.
-S ~/src/openstreetmap-carto/openstreetmap-carto.style: Створювати стовпці в базі даних використовуючи вказаний файл (в нашому випадку він нічим не відрізняється від стандартного "openstreetmap-carto")
~/data/azerbaijan-latest.osm.pbf: Останній аргумент – це файл з даними для завантаження в базу.

Результатом роботи цієї команди має бути щось схоже на "Osm2pgsql took 238s overall".

Створення індексів⚓︎

Починаючи з версії 5.3.0, деякі додаткові індекси мають бути застосовані вручну:.

cd ~/src/openstreetmap-carto/
sudo -u _renderd psql -d gis -f indexes.sql

Скрипт має повідомити CREATE INDEX 16 разів.

Функції бази даних⚓︎

У версії 5.9.0 «OSM Carto» (випущена в жовтні 2024 року) деякі функції потрібно завантажувати в базу даних вручну. Вони можуть бути додані/перезавантажені в будь-який момент за допомогою:

cd ~/src/openstreetmap-carto/
sudo -u _renderd psql -d gis -f functions.sql

Завантаження Shapefile⚓︎

Попри те, що більшість даних для створення мапи береться з файлу з даними OpenStreetMap, який ви завантажили раніше, деякі файли в форматі shapefile все ж такі потрібні для таких речей, наприклад, як кордони країн на великих масштабах. Завантажте їх та проіндексуйте:

cd ~/src/openstreetmap-carto/
mkdir data
sudo chown _renderd data
sudo -u _renderd scripts/get-external-data.py

Цей процес вимагає завантаження великої порції даних та триватиме деякий час без будь-яких помітних змін на екрані. Частина даних записується безпосередньо у базу даних, а інша у підтеку "data" в "openstreetmap-carto". Якщо у вас тут виникнуть проблеми, то це скоріше через те, що дані Natural Earth можуть бути не в тому місці. Якщо вам потрібно змінити місце куди ви завантажуєте дані Natural Earth – внесіть зміни у власну копію цього файлу.

Шрифти⚓︎

Починаючи з версії v5.6.0 шрифти для Carto потрібно встановити вручну:

cd ~/src/openstreetmap-carto/
scripts/get-fonts.sh

Наші тестові дані (Азербайджан) були обрані через їх невеликий обсяг, а також через те, що армянська писемність використовує власну абетку.

Налаштування вебсервер⚓︎

Конфігурація renderd⚓︎

Налаштування renderd в Debian 12 знаходяться у файлі /etc/renderd.conf. Відредагуємо його за допомогою текстового редактора, такого як nano:

sudo nano /etc/renderd.conf

Додайте розділ, подібний наведеному, в кінець файлу налаштувань:

[s2o]
URI=/hot/
TILEDIR=/var/lib/mod_tile
XML=/home/accountname/src/openstreetmap-carto/mapnik.xml
HOST=localhost
TILESIZE=256
MAXZOOM=20

Можливо розташування файлу XML /home/accountname/src/openstreetmap-carto/mapnik.xml доведеться змінити на те, що використовується у вашій системі. Ви можете змінити [s2o] та URI=/hot/ на те, що вам треба. Якщо ви бажаєте рендерити більше одного набору тайлів на одному сервері, ви можете додати ще один розділ, подібний до [s2o], з налаштуваннями для іншого стилю. Якщо ви бажаєте, щоб він посилався на іншу базу замість типової gis, ви також можете зробити це, але пояснення того, як це робити виходить за межі цього документа. Якщо у вас десь 2 Гб оперативної памʼяті, можливо вам доведеться зменшити кількість потоків (num_threads) до 2. URI=/hot/ було обрано для того щоби було простіше використовувати ваші тайли замість шару Humanitarian з сайту OpenStreetMap.org. Ви можете вказати щось інше, але /hot/ також годиться.

Версія Mapnik в Debian 12 була 3.1, тому налаштування plugins_dir у частині [mapnik] файлу було /usr/lib/mapnik/3.1/input. Це може змінитися в майбутньому. У разі виникнення помилки під час спроб рендерингу тайлів, на кшталт цієї:

An error occurred while loading the map layer 's2o': Could not create datasource for type: 'postgis' (no datasource plugin directories have been successfully registered) encountered during parsing of layer 'landcover-low-zoom'

перевірте /usr/lib/mapnik та подивіться, яка версія в назві теки, а також погляньте на /usr/lib/mapnik/(version)/input, щоб переконатись, що файл postgis.input знаходиться там.

Тепер, коли ми вказали renderd, як реагувати на запити рендерингу тайлів, нам потрібно повідомити вебсерверу Apache, що він може надсилати їх. На жаль, конфігурацію для цього було видалено з останніх версій mod_tile. Однак зараз її можна встановити звідси:

cd /etc/apache2/conf-available/
sudo wget https://raw.githubusercontent.com/openstreetmap/mod_tile/python-implementation/etc/apache2/renderd.conf
sudo a2enconf renderd
sudo systemctl reload apache2

Переконайтеся, що у вас є повідомлення для відлагодження⚓︎

На цьому етапі було б дуже корисно мати можливість побачити результат процесу рендерингу тайлів, включно з будь-якими помилками. Стандартно в останніх версіях mod_tile цю можливість вимкнено. Щоб її увімкнути:

sudo nano /usr/lib/systemd/system/renderd.service

Якщо немає, додайте наступний рядок

Environment=G_MESSAGES_DEBUG=all

після “[Service]”. Далі:

sudo systemctl daemon-reload
sudo systemctl restart renderd
sudo systemctl restart apache2

Конфігурація Apache⚓︎

sudo mkdir /var/lib/mod_tile
sudo chown _renderd /var/lib/mod_tile

Потім перезапустіть службу renderd:

sudo /etc/init.d/renderd restart

Якщо ви подивіться у системний журнал, ви повинні побачити повідомлення від служби renderd. Зауважте, що у Debian 12, повідомлення більше стандартно не записуються в /var/log/syslog – щоб стежити за повідомленнями, коли вони там зʼявляються, виконайте наступне:

sudo journalctl -ef

Дивіться тут: для ознайомлення з деталями.

sudo /etc/init.d/apache2 restart

Виконавши команду sudo journalctl -ef ви маєте побачити рядок подібний до цього:

Jul 01 01:50:28 h4-debian-16gb-fsn1-1 apachectl[34625]: [Sat Jul 01 01:50:28.260957 2023] [tile:notice] [pid 34625:tid 281473357369376] Loading tile config s2o at /hot/ for zooms 0 - 20 from tile directory /var/cache/renderd/tiles with extension .png and mime type image/png

Якщо ви не побачите нічого подібного, це, ймовірно, означатиме, що файл конфігурації для mod_tile /etc/apache2/conf-available/renderd.conf або не налаштовано, або ввімкнено належним чином — дивіться розділ wget вище.

Далі, відкрийте в оглядачі http://ip.вашого.сервера/index.html (замініть ip.вашого.сервера на відповідну адресу). Ви маєте побачити типову сторінку сервера Apache2 встановленого в Debian.

Порада

якщо ви не знаєте IP адресу призначену серверу, її можна дізнатись за допомогою команди ifconfig – якщо мережеві налаштування не надто складні, то це має бути щось типу inet addr відмінне від 127.0.0.1.

Якщо ви використовуєте сервер постачальника послуг хостингу, то, швидше за все, внутрішня адреса вашого сервера буде відрізнятися від зовнішньої адреси, яка була надана вам, але ця зовнішня IP-адреса вже буде надіслана вам, і, ймовірно, ви її використовуєте зараз для доступу до сервера.

Зауважте, що це лише сайт http (порт 80) – вам потрібно витратити трохи більше часу для налаштування Apache на використання https, але це виходить за межі цих інструкцій. Однак якщо ви використовуєте "Let's Encrypt" для отримання сертифікатів, інструкція зі встановлення може також містити поради щодо налаштування сайту Apache для використання https.

Далі, в оглядачі відкрийте посилання: http://ip.вашого.сервера/hot/0/0/0.png

Якщо ви вище поміняли URI=/hot/ вам доведеться підправити посилання. Ви маєте побачити маленьку мапу світу. Якщо її немає, перевірте повідомлення про помилки в консолі. Скоріш за все ви щось наплутали з дозволами, або ви пропустили якийсь крок з інструкції. Якщо ви не отримали тайл та отримуєте інші посилання, скопіюйте вивід в Pastebin, та зверніться за допомогою, наприклад, в community.openstreetmap.org.

Перегляд тайлів⚓︎

Для того, щоб побачити тайли, ми трохи змахлюємо користуючись файлом sample_leaflet.html з теки “extras” в mod_tile.

cd /var/www/html
sudo wget https://raw.githubusercontent.com/SomeoneElseOSM/mod_tile/switch2osm/extra/sample_leaflet.html
sudo nano sample_leaflet.html

Змініть його так, щоб IP-адреса була ip.вашого.сервера, а не просто 127.0.0.1. Це повинно дозволити вам отримати доступ до цього сервера. Потім перейдіть до http://ip.вашого.сервера/sample_leaflet.html.

Згодом ви побачите мапу. Ви зможете збільшувати та зменшувати її масштаб, але в залежності від потужностей сервера, деякі тайли можуть бути сірими (вони ще не встигли обробитись сервером). Однак, як тільки їх обробка завершиться, вони будуть готові для перегляду. Якщо ви подивитесь у системний лог, ви маєте побачити запити на показ тайлів.

За бажанням, ви можете збільшити значення ModTileRequestTimeout та ModTileMissingRequestTimeout у /etc/apache2/conf-available/renderd.conf з 3 та 10 секунд до, скажімо, 30 або 60, для того, щоб дати більше часу серверу на створення тайлів перед тим як показати сірий фон на замість них. Перевірте, що ви виконали команди service renderd restart та service apache2 restart після внесення змін.

Вітаємо! Тепер ви можете повернутись до розділу Використання тайлів для додавання мапи, що використовує ваш новий тайловий сервер.