Saltar a contenido

Guía de instalación y ejecución para desarrolladores

En este documento se detallan los pasos a seguir si se desea configurar un servidor de API Georef propio.

Dependencias

Instalación

1. Elasticsearch

Para instalar Elasticsearch, seguir las siguientes instrucciones en uno o más servidores (nodos).

1.1 Instalar Elasticsearch

Instalar Elasticsearch siguiendo la guía de instalación para Debian/Ubuntu.

1.2 Habiliar el servicio elasticsearch

Asegurar que el servicio elasticsearch está habilitado utilizando systemctl:

$ sudo systemctl start elasticsearch
$ sudo systemctl enable elasticsearch

1.3 Aplicar las configuraciones recomendadas

Editar el archivo /etc/elasticsearch/elasticsearch.yml. El valor de node.name debe ser único por nodo, y todos los nodos deben tener el mismo valor de cluster.name:

cluster.name: georef-ar-api
node.name: node-1

Editar el archivo /etc/elasticsearch/jvm.options (siguiendo las recomendaciones de Elasticsearch):

# Tamaño del heap size de la JVM
# Se recomienda utilizar siempre el mismo valor como mínimo y máximo
# Ejemplo: 4 GB
-Xms4g
-Xmx4g

2. Repositorio y dependencias

2.1 Clonar el repositorio:

$ git clone https://github.com/datosgobar/georef-ar-api.git
$ cd georef-ar-api

2.2 Crear un entorno virtual y activarlo

$ python3 -m venv venv
$ source venv/bin/activate

2.3 Instalar dependencias con pip

(venv) $ pip3 install -r requirements.txt -r requirements-dev.txt

2.4 Copiar el archivo de configuración

(venv) $ cp config/georef.example.cfg config/georef.cfg

Luego, completar el archivo config/georef.cfg con los valores apropiados.

2.5 Copiar el archivo de configuración de logs

(venv) $ cp config/logging.example.ini config/logging.ini

Luego, completar el archivo config/logging.ini con los valores apropiados. Los valores por defecto son válidos y pueden ser utilizados en entornos productivos.

3. Crear los índices

El siguiente paso es indexar todos los datos de entidades geográficas en Elasticsearch, para poder consultarlos vía el servidor de la API. Para lograr esto, la API acepta una serie de archivos NDJSON donde deberían estar almacenados los datos. La estructura de dichos archivos está detallada en este documento.

El archivo de configuración config/georef.cfg debe especificar una ruta local o una URL externa para cada archivo de datos NDJSON. Notar que los valores por defecto (en georef.example.cfg) utilizan el portal de descargas infra.datos.gob.ar, que siempre provee la última versión de los archivos NDJSON disponibles. La rama master de georef-ar-api siempre se mantiene compatible con la última versión de los datos disponibles en infra.datos.gob.ar. El archivo de configuración también debe especificar la URL del archivo de sinónimos para utilizar al momento de indexar campos de texto en Elasticsearch. El valor por defecto en georef.example.cfg también puede ser utilizado, ya que utiliza la versión del archivo almacenado en infra.datos.gob.ar. El mismo criterio se aplica al archivo de términos excluyentes. En resumen, si se utilizó georef.example.cfg como base para configurar la API, las URLs de los archivos ya deberían estar configuradas correctamente.

Para indexar los datos, ejecutar:

(venv) $ make index

Listar los índices creados, y otros datos adicionales:

(venv) $ make print_index_stats

4. (Opcional) Re-indexar datos

Si se modifican los archivos de datos NDJSON, es posible re-indexarlos sin borrar los índices ya existentes. Dependiendo del comportamiento que se desee, se debe tomar una opción:

Indexar datos nuevos

Si se desea actualizar los índices con los nuevos datos, pero solo si los datos entrantes son más recientes que los ya indexados, se puede utilizar nuevamente la receta index:

(venv) $ make index

Forzar re-indexado

Si se desea forzar un re-indexado, es decir, si se desea indexar los datos nuevamente sin importar la fecha de creación, se debe utilizar la siguiente receta:

(venv) $ make index_forced

La receta index_forced intenta utilizar un archivo de respaldo guardado anteriormente si no pudo acceder a los archivos especificados en config/georef.cfg. El uso de la receta es recomendado cuando se requiere re-indexar los datos incondicionalmente. Algunas de las situaciones donde esto es necesario son:

  • Modificación de la estructura de los archivos de datos
  • Modificación de mappeos de tipos de Elasticsearch
  • Modificación de analizadores de texto de Elasticsearch
  • Modificación de listado de sinónimos
  • Modificación de listado de términos excluyentes

Cualquiera de las dos opciones también permite indexar datos selectivamente: se debe especificar el nombre del índice a crear/re-indexar. Por ejemplo:

(venv) $ make index INDEX_NAME=localidades
(venv) $ make index_forced INDEX_NAME=calles

Los nombres de los índices disponibles son:

  • provincias
  • provincias-geometria
  • departamentos
  • departamentos-geometria
  • municipios
  • municipios-geometria
  • localidades-censales
  • asentamientos
  • localidades
  • calles
  • intersecciones
  • cuadras

5. Correr API

Entornos de desarrollo

Correr la API de Georef utilizando un servidor de prueba (no apto para producción):

(venv) $ make start_dev_server

O También:

(venv) $ make start_gunicorn_dev_server

Entornos productivos

5.1 Configurar servicio georef-ar-api para systemd

Copiar el archivo config/georef-ar-api.service a /etc/systemd/system/ y configurarlo. Notar los campos marcados entre '<' y '>', que deben ser reemplazados por el usuario.

5.2 Activar y arrancar el servicio
$ sudo systemctl daemon-reload
$ sudo systemctl enable georef-ar-api.service
$ sudo systemctl start georef-ar-api.service
5.3 Configurar nginx

Primero, crear /etc/nginx/sites-available/georef-ar-api.nginx tomando como base la configuración del archivo georef-ar-api.nginx.

5.4 (Opcional) Crear cache para nginx

Si se desea activar el uso del cache de nginx, descomentar las líneas contentiendo las directivas proxy_cache y proxy_cache_valid del archivo georef-ar-api.nginx creado. Luego, activar el cache georef agregando la siguiente línea al archivo de configuración nginx.conf (sección http):

proxy_cache_path /data/nginx/cache levels=1:2 inactive=120m keys_zone=georef:10m use_temp_path=off;

Finalmente, crear el directorio /data/nginx/cache.

5.5 Activar y validar configuración nginx

Generar un link simbólico a la configuración del sitio:

$ sudo ln -s /etc/nginx/sites-available/georef-ar-api.nginx /etc/nginx/sites-enabled/georef-ar-api.nginx

Validar la configuración:

$ sudo nginx -T

Reiniciar Nginx:

$ systemctl restart nginx.service

Tests

Para ejecutar los tests unitarios (el servicio Elasticsearch debe estar activo y con los datos apropiados cargados):

(venv) $ make test

Para más información sobre los tests, ver el archivo tests/README.md.

Para comprobar que no existan errores comunes en el código, y que su estilo sea correcto:

(venv) $ make code_checks