README.md

# Geocubo Portable

Este proyecto permite a un usuario realizar diferentes tipos de análisis geoestadísticos, a través de programación en Python, sobre diferentes zonas de estudio. El proyecto hace uso de los productos generados por el CDGM de INEGI.

Es una versión compacta del Cubo de Datos Geoespacial de INEGI; pues en su base de datos solo hace referencia a los archivos de Geomedianas de los años de 1993 a 2019, es decir, que todas las consultar que se hagan desde el Geocubo Portable serán resueltas a partir de las Geomedianas indexadas en él.

# Prerequisitos de instalación
    1. Sistema operativo Windows 10 Pro o Ubuntu 18+.
    2. Procesador de 4 núcleos.
    3. 8GB de memoria RAM.
    4. 100 GB de almacenamiento disponible. La cantidad puede variar dependiendo de la cantidad de imágenes que se desee analizar, cada Geomediana nacional pesa alrededor de 35 GB y el total de espacio que ocupan todas las geomedianas es de 1 TB.

# Recursos necesarios
## Estructura de archivos
El Geocubo Portable requiere de una estructura de archivos para su correcto funcionamiento.
#### Enlace para descargar estructura de archivos:

https://365inegi-my.sharepoint.com/:u:/g/personal/armando_soto_inegi_org_mx/EYI6vT513DNJlLijteyR1M4B0RiVnDvKH_FMeub_mZXIIA?e=ydgtYu

El archivo que se descarga se llama **“Almacenamiento.zip”** y se suguiere que sea descompactado en la raíz de alguna unidad de almacenamiento (C:/, D:/, para el caso de Windows; /home/user/, para el caso de Ubuntu) de manera que sea más fácil hacer referencia a él más adelante.

La carpeta de Almacenamiento contiene dos subcarpetas.

![Almacenamiento](images-project/Almacenamiento.PNG "Carpeta Almacenamiento")

## Proyecto en gitlab
Otro elemento necesario para instalar el Cubito de datos es el proyecto de geocubo-portable publicado en el gitlab institucional de INEGI. Se recomienda clonarlo con Git para tener las actualizaciones más recientes, sin embargo, basta con descargarlo.
Descargar el proyecto en formato **ZIP** y se sugiere sea almacenado y descompactado en la carpeta de “Documentos”.

![Descarga](images-project/Descargar_proyecto.png "Descargar prooyecto")

## Imagen de Docker con el Geocubo Portable
El último elemento que se necesita es la imagen de docker que contiene todo el software necesario para el correcto funcionamiento del Geocubo Portable.
#### Enlace para descargar la imagen de Docker

https://drive.google.com/file/d/1oXSHo2mvRJW4043qwd9z9z-4ZC1873jK/view?usp=sharing

![Imagen_docker](images-project/Imagen_docker.png "Imagen docker")\
Este archivo tiene un formato **TAR** y un tamaño mayor a los 4 GB, por lo que su descarga puede demorar varios minutos, se sugiere sea almacenado en la carpeta de “Documentos” para facilitar su acceso más adelante.

## Docker
Tecnología para la creación y uso de contenedores de linux; permite crear diferentes ambientes de trabajo para la ejecución de aplicaciones.

Descargar el instalador **Docker Desktop Installer.exe** la versión estable más actual.
#### Enlace para descargar

https://hub.docker.com/editions/community/docker-ce-desktop-windows

![Descargar_docker](images-project/Descarga_docker.png "Descargar docker")

El archivo pesa alrededor de 500MB por lo que demora un poco en descargarse.

# Instalación de Docker
### En Windows
1. Una vez que se descargue el instalador de Docker, procedemos a su instalación haciendo doble clic sobre el archivo descargado para que inicie el asistente de instalación.

2. Se abrirá una ventana de instalación de Docker.\
Comenzará a descargar los archivos necesarios para la instalación.\
![Descarga](images-project/Inst_Window1.png "Descarga")\

3. Establecer todas las configuraciones por defecto o recomendadadas por el asistente de instalación, dar clic en el botón Ok.\
![Configuracion](images-project/Inst_Window2.PNG "Configuracion")
4. Continuará con la instalación.\
![Instalacion](images-project/Inst_Window3.png "Instalacion")\

5. Finalizar instalación.\
Dar clic en close and restart.\
![Close](images-project/Inst_Window4.png "Close")\
El asistente de instalación pedirá reiniciar el equipo al finalizar la instalación.\
Se creará un icono en el escritorio de Windows, dar clic en el icono de Docker.


### En Ubuntu
1. Actualizar repositorios con el comando:\
**sudo apt update**\
![Actualizar_repositorios](images-project/Inst_Ubuntu1.png "Actualizar repositorios")\
Nota: Si el comando le pide que se actualicen paquetes del sistema operativo será necesario ejecutar el siguiente comando:\
**sudo apt-get upgrade**\
![Actualizar_paquetes](images-project/Inst_Ubuntu1a.png "Actualizar paquetes")\
Enseguida volver a ejecutar el comando update
2. Instalar algunos paquetes que permiten a apt usar paquetes mediante https:\
**sudo apt install apt-transport-https ca-certificates curl software-properties-common**
![Instalar_paquetes](images-project/Inst_Ubuntu2.png "Instalar paquetes")\
3. Agregar la clave GPG para el repositorio oficial de Docker a su sistema:\
**curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add –**
![Agregar_clave](images-project/Inst_Ubuntu3.png "Agregar clave")\
4. Agregar el positorio de Docker a las fuentes de apt:\
**sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"**
![Agregar_repositorio](images-project/Inst_Ubuntu4.png "Agregar repositorio")\
5. Actualizar la base de datos de paquetes usando los paquetes de Docker del repositorio que se acaba de Agregar:\
**sudo apt update**
6. Instalar Docker:\
**sudo apt install docker-ce**\
![Instalar_docker](images-project/Inst_Ubuntu6.png "Instalar docker")\
7. Verificar que se esté ejecutando:\
**sudo systemctl status docker**\
![Verificiar_docker](images-project/Inst_Ubuntu7.png "Verificar docker")\
De forma predeterminada, el comando docker solo se puede ejecutar por el usuario de root o por un usuario perteneciente al grupo docker, el cual se creó durante la instalación de Docker. Si intenta ejecutar el comando docker sin el prefijo sudo o sin estar en el grupo docker, en la consola se mostrará un mensaje como el siguiente:\
docker: Cannot connect to the Docker daemon. Is the docker daemon running on this host?. See 'docker run --help'.\
Para agregar su nombre de usuario al grupo docker y así evitar escribir sudo antes ejecutar el comando docker, ejecute lo siguiente:\
**sudo usermod -aG docker ${USER}**\
Para aplicar la nueva membresía de grupo, debe cerrar sesión en el servidor y volver a iniciarla, o puede ejecutar lo siguiente:\
**su - ${USER}**\
![Membresia_grupo](images-project/Inst_Ubuntu7a.png "Membresia grupo")\
8. Para probar que todo funciona correctamente, ejecutar el siguiente comando para obtener información de Docker en su sistema:\
**docker info**\
![Informacion](images-project/Inst_Ubuntu8.png "Informacion")\
9. Instalación de una utilería de Docker para hacer usar correctamente el Geocubo Portable. Ejecutar el siguiente comando:\
**sudo apt install docker-compose**\
![Utileria_docker](images-project/Inst_Ubuntu9.png "Utileria docker")\
# Ejecutar el software en nuestro equipo
El Geocubo portable requerie el uso de contenedores y microservicios que se ejecutan a través de la consola de comandos PowerShell.\
Añadir la imagen al repositorio de nuestro Docker local que es la imagen de docker que se descargó desde el inicio de este manual, que tiene un tamaño aproximado de 4GB. Dicha imagen contiene la instalación de todas las librerías que se requieren para el correcto funcionamiento del Geocubo Portable.
1. Abrir una terminal en Linux o una consola de Windows Power Shell.

2. Colocarse en la ubicación donde se descargó la imagen:\
**cd .\Documents**
3. Añadir la imagen con el siguiente comando:\
**docker load -i .\CubitoDatos.tar**\
Este paso puede tardar algunos minutos, pero una vez que termine se puede ver que se agregó a la lista de imágenes en docker a través del siguiente comando:\
**docker image ls**\
![Imagen_load](images-project/Imagen_load.png "Imagen añadida")\
4. Verificar el archivo docker-compose.yml que se encuentra en la raíz.\
Para continuar con el proceso de instalación del GeoCubo Portable, es necesario modificar el archivo docker-compose.yml que se encuentra en la raíz del proyecto que se descargó de gitlab previamente. Las líneas a revisar se encuentran señaladas en la siguiente imagen:\
![Archivo](images-project/Archivo_yml.png "Archivo")\
Nota: Si estas en el sistema operativo de Windows y la carpeta Almacenamiento la tienes ubicada en C:/, la raíz del sistema, no es necesario que hagas ninguna modificación en el archivo antes mencionado y puedes continuar con el siguiente paso, resaltado en negritas en la siguiente pagina.
5. Moverse a la ubicación del proyecto:\
cd '.\Documents\datacube-inegi-on-docker\'\
En caso de que recién ejecutarás Power Shell, si continuas con la misma ventana con la que cargaste la imagen de docker es con el siguiente comando:\
cd 'datacube-inegi-on-docker\'

6. Activar e iniciar tareas de los contenedores de Docker con el siguiente comando:\
**docker-compose up -d**\
![Activar_contenedores](images-project/Docker_compuse.png "Activar contenedores")\
Una vez que se haya ejecutado el comando los contenedores de Docker para el Geocubo Portable estarán activos e iniciando sus tareas, se podrán monitorear desde el Dashboard.

# Iniciar un cuaderno de Jupyter
Es una herramienta que nos permite ejecutar un código en Python al mismo tiempo que se va explicando.
1. Iniciar contenedor.\
Si el contenedor con el Cubito de Datos ya se encuentra disponible en su equipo, pero no se está ejecutando, es necesario que desde una terminal en Linux o una consola de Power Shell de Windows, se ubiquen en la raíz del proyecto de gitlab y se ejecute el siguiente comando:\
**docker-compose up –d**
2. Iniciar cuaderno de Jupyter.\
Para poder iniciar el cuaderno de descargas habrá que acceder al siguiente link desde cualquier navegador web:\
http://127.0.0.1:8888/?token= 
Al ingresar al sitio se solicita una contraseña, es la siguiente: **datacubeOnDocker**\
Página web:\
![Jupyter](images-project/Jupyter.png "Inicio Jupyter")\
En la ventana se muestra como un explorador de archivos, donde se pueden crear o consultar cuadernos de Jupyter con código que interactúe directamente con el GeoCubo Portable.
2. Descargar imágenes.\
El Geocubo Portable requiere de imágenes para poder hacer las consultas de los cuadernos, estás imágenes se almacenen en la carpeta Almacenamiento que se presentó al principio de este manual, sin embargo, de inicio la carpeta no contiene ninguna imagen y será necesario ejecutar el cuaderno para descargas de imágenes.\
La carpeta **Descargas** contiene el cuaderno que se debe iniciar para la **descarga de imágenes**. El cuaderno está listo para descargar las imágenes que comprenden al estado de Aguascalientes, basta con abrirlo y seguir las instrucciones.







# Solución a posibles errores