Install ApiDQ application

Install ApiDQ application #

The instruction is written for Ubuntu 24.04 LTS.

Install docker #

Docker Engine and the Docker Compose plugin are installed from the official Docker repository.

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 is installed as a plugin (the docker-compose-plugin package) and is invoked with the docker compose command. The standalone docker-compose 1.x binary is no longer used.

Executing the Docker command without sudo #

If you want to avoid typing sudo whenever you run the docker command, add your username to the docker group:

 sudo usermod -aG docker ${USER}

To apply the new group membership, log out of the server and back in, or type the following:

 su - ${USER}

You will be prompted to enter your user’s password to continue.

Connect to ApiShip Docker Registry #

docker login gitlab.apiship.ru:5050

Username: gitlab_login - login to access the GitLab server
Password: gitlab_password - password to access the GitLab server

Setting up and running the application #

Create apidq folder

mkdir ~/apidq
cd ~/apidq

Creating of configuration files #

Depending on the connected functionality, the set of services may differ. You can check the current list with support.

The Level parameter of the logger section sets the minimum log level: debug, info, warn or error.

Create file address-config.toml with the following content

[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 - the license key received from ApiDQ team. The ProlongationServer parameter enables automatic license key prolongation, it requires api.apidq.io:443 to be reachable from the server. The license state can be checked with the license get service.

If the database is installed on the same server as the application, set Address to the Docker network gateway address - 172.17.0.1. Inside a container 127.0.0.1 points to the container itself, not to the server.

Create file phone-config.toml with the following content

[main]
ListenAddr = "0.0.0.0"
ListenPort = "8081"
Debug = false
[logger]
Facility = "apidq-service-phone"
Level = "warn"

Create file name-config.toml with the following content

[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"

Create file gateway-config.toml with the following content

[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 metrics: GET /metrics

The image version is set in one place - the .env file. Create file .env and specify the ApiDQ version to install (the list of versions is on the page changelog)

APIDQ_VERSION=1.22.0
Do not use the latest tag: the application version must match the versions of dictionaries in the database (block Requirements for versions of dictionaries), and a pinned version makes it possible to roll back to the previous one.

Create file docker-compose.yaml with the following content

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

On startup the address service loads dictionaries into memory (about a minute) and starts accepting requests only after that. The healthcheck block tracks its readiness, and gateway starts after address is ready.

The -health-check readiness probe is available starting from version 1.21.1. For earlier versions remove the healthcheck block of the address service and replace the service_healthy condition of gateway with service_started - otherwise docker compose up -d fails with dependency failed to start.

Run and check application #

 docker compose up -d

The command completes after the address service has loaded the dictionaries. Service status:

 docker compose ps

Check application readiness - the response is 200 when all services are ready to accept requests, otherwise 503

curl -i http://127.0.0.1:8080/health
Use GET /health as the server health check in a load balancer

The -w parameter prints the HTTP code after the response - a successful request ends with the line HTTP 200.

Check 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"
}'

Check 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}'

Check license

curl 'http://127.0.0.1:8080/api/v1/license'

Application autostart #

The restart: always parameter restarts containers after a failure and after a server reboot. For reliable autostart we recommend installing a systemd service in addition.

Create file /etc/systemd/system/apidq.service with the following content. Replace apidq_user with the user the application is installed under.

The service runs docker compose as this user, so the user must be a member of the docker group - see Executing the Docker command without sudo. Otherwise the service fails to start with 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

Enable the service

sudo systemctl daemon-reload
sudo systemctl enable --now apidq.service