Установка ApiDQ приложения #
Инструкция написана для Ubuntu 24.04 LTS.
Установка docker #
Docker Engine и плагин Docker Compose устанавливаются из официального репозитория Docker.
sudo apt update
sudo apt install ca-certificates curl gnupg
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /usr/share/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
Docker Compose устанавливается как плагин (пакетdocker-compose-plugin) и вызывается командойdocker compose. Отдельный бинарный файлdocker-composeверсии 1.x больше не используется.
Выполнение команды Docker без sudo #
Если вы не хотите вводить sudo при каждом запуске команды docker, добавьте свое имя пользователя в группу docker:
sudo usermod -aG docker ${USER}
Чтобы изменения вступили в силу, выйдите из сервера и снова войдите или введите следующее:
su - ${USER}
Вам будет предложено ввести пароль пользователя, чтобы продолжить.
Подключение к ApiShip Docker Registry #
docker login gitlab.apiship.ru:5050
Username: gitlab_login - логин доступа к серверу GitLab
Password: gitlab_password - пароль доступа к серверу GitLab
Настройка и запуск приложения #
Создайте apidq папку
mkdir ~/apidq
cd ~/apidq
Создание файлов конфигурации #
В зависимости от подключенного функционала, набор сервисов может отличать. Актуальный список можно уточнить в поддержке.
Параметр Level секции logger задаёт минимальный уровень записи в лог: debug, info, warn или error.
Создайте файл address-config.toml следующего содержания
[main]
ListenAddr = "0.0.0.0" # ip address where the address service will be available
ListenPort = "8083" # port where the address service will be available
Debug = false
[logger]
Facility = "apidq-service-address"
Level = "warn"
[postgresql]
Address = "192.168.0.10" # ip postgresql server
Port = "5432" # port postgresql server
Dbname = "db_apidq" # apidq database
User = "user_apidq"
Password = "p_a_s_s_w_o_r_d"
[license]
Key = "LICENSE_KEY"
ProlongationServer = "https://api.apidq.io/v1"
LICENSE_KEY - лицензионный ключ, полученный от команды ApiDQ. Параметр ProlongationServer включает автоматическое продление лицензионного ключа, для него с сервера должен быть доступен api.apidq.io:443. Состояние лицензии можно проверить
сервисом получения лицензии.
Если база данных установлена на том же сервере, что и приложение, укажите вAddressадрес шлюза сети Docker -172.17.0.1. Адрес127.0.0.1внутри контейнера указывает на сам контейнер, а не на сервер.
Создайте файл phone-config.toml следующего содержания
[main]
ListenAddr = "0.0.0.0"
ListenPort = "8081"
Debug = false
[logger]
Facility = "apidq-service-phone"
Level = "warn"
Создайте файл name-config.toml следующего содержания
[main]
ListenAddr = "0.0.0.0"
ListenPort = "8082"
Debug = false
[logger]
Facility = "apidq-service-name"
Level = "warn"
[postgresql]
Address = "192.168.0.10" # ip postgresql server
Port = "5432" # port postgresql server
Dbname = "db_apidq" # apidq database
User = "user_apidq"
Password = "p_a_s_s_w_o_r_d"
Создайте файл gateway-config.toml следующего содержания.
[main]
ListenAddr = "0.0.0.0" # ip address where service will be available
ListenPort = "8080" # port where service will be available
ReadTimeout = 60000
WriteTimeout = 60000
Debug = false
[logger]
Facility = "apidq-service-gateway"
Level = "warn"
[addressService]
Enabled = true
EndpointAddr = "address" # ip address or host service from address-config.toml
EndpointPort = "8083" # port service from address-config.toml
[phoneService]
Enabled = true
EndpointAddr = "phone"
EndpointPort = "8081"
[nameService]
Enabled = true
EndpointAddr = "name"
EndpointPort = "8082"
[metrics]
Enabled = true # метрики в формате Prometheus: GET /metrics
Версия образов задаётся в одном месте - в файле .env. Создайте файл .env и укажите в нём устанавливаемую версию ApiDQ (список версий - на странице
История изменений)
APIDQ_VERSION=1.22.0
Не используйте тегlatest: версия приложения должна соответствовать версиям справочников в базе данных (блокТребования к версиям справочников), а зафиксированная версия позволяет выполнить восстановление на предыдущую.
Создайте файл docker-compose.yaml следующего содержания.
services:
gateway:
image: "gitlab.apiship.ru:5050/apidq/apidq/apidq-service-gateway:${APIDQ_VERSION}"
restart: always
ports:
- "8080:8080"
volumes:
- ./gateway-config.toml:/dist/config.toml
depends_on:
address: { condition: service_healthy }
name: { condition: service_started }
phone: { condition: service_started }
healthcheck:
test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/health"]
interval: 10s
timeout: 3s
retries: 3
start_period: 20s
address:
image: "gitlab.apiship.ru:5050/apidq/apidq/apidq-service-address:${APIDQ_VERSION}"
restart: always
volumes:
- ./address-config.toml:/dist/config.toml
healthcheck:
test: ["CMD", "/dist/service-address", "-health-check"]
interval: 10s
timeout: 3s
retries: 3
start_period: 300s
phone:
image: "gitlab.apiship.ru:5050/apidq/apidq/apidq-service-phone:${APIDQ_VERSION}"
restart: always
volumes:
- ./phone-config.toml:/dist/config.toml
name:
image: "gitlab.apiship.ru:5050/apidq/apidq/apidq-service-name:${APIDQ_VERSION}"
restart: always
volumes:
- ./name-config.toml:/dist/config.toml
Сервис address при запуске загружает справочники в память (около минуты) и начинает принимать запросы только после этого. Блок healthcheck отслеживает его готовность, а gateway запускается после того, как address готов.
Проверка готовности-health-checkдоступна начиная с версии 1.21.1. Для более ранних версий удалите блокhealthcheckу сервисаaddressи замените уgatewayусловиеservice_healthyнаservice_started- иначеdocker compose up -dзавершится ошибкойdependency failed to start.
Запустить и проверить приложение #
docker compose up -d
Команда завершится после того, как сервис address загрузит справочники. Состояние сервисов:
docker compose ps
Проверить готовность приложения - ответ 200, когда все сервисы готовы принимать запросы, иначе 503
curl -i http://127.0.0.1:8080/health
Используйте GET /health для проверки доступности сервера в балансировщике нагрузкиПараметр -w выводит после ответа код HTTP - успешный запрос завершается строкой HTTP 200.
Проверить clean/address (стандартизация адресов)
curl -w '\nHTTP %{http_code}\n' --location --request POST 'http://127.0.0.1:8080/api/v1/clean/address' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "котлас кузнецова 14в 132",
"countryCode": "RU"
}'
Проверить suggest/address (адресные подсказки)
curl -w '\nHTTP %{http_code}\n' --location --request POST 'http://127.0.0.1:8080/api/v1/suggest/address' \
--header 'Content-Type: application/json' \
--data-raw '{"query": "москва варш","countryCode": "RU","count": 2}'
Проверить лицензию
curl 'http://127.0.0.1:8080/api/v1/license'
Автозапуск приложения #
Параметр restart: always перезапускает контейнеры после сбоя и после перезагрузки сервера. Для надёжного автозапуска рекомендуем дополнительно установить systemd-сервис.
Создайте файл /etc/systemd/system/apidq.service следующего содержания. Замените apidq_user на пользователя, под которым установлено приложение.
Сервис запускаетdocker composeот имени этого пользователя, поэтому он обязательно должен состоять в группеdocker- см. Выполнение команды Docker без sudo. Иначе сервис не запустится с ошибкойpermission denied.
[Unit]
Description=ApiDQ backend (docker compose)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target
[Service]
Type=oneshot
RemainAfterExit=yes
User=apidq_user
Group=apidq_user
WorkingDirectory=/home/apidq_user/apidq
ExecStart=/usr/bin/docker compose up -d --remove-orphans
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0
[Install]
WantedBy=multi-user.target
Включите сервис
sudo systemctl daemon-reload
sudo systemctl enable --now apidq.service