Установка ApiDQ приложения

Установка 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