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¶
- Elasticsearch >=7.0.0
- Python >=3.6.0
- Nginx (para entornos productivos)
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