Instalar e iniciar la aplicación¶

Esta página le indica cómo instalar, iniciar, detener, actualizar y eliminar LUC Analytics (LUCA) en un portátil con Windows o en un equipo Mac, con Docker Desktop.

En un equipo Mac, haga primero los pasos de "Instalar en un equipo Mac". Luego continúe en "Iniciar el contenedor".

Instalar o actualizar con un solo comando¶

El script de instalación es la forma más rápida de instalar o actualizar la aplicación. El script hace por usted los pasos de esta página. Las secciones que siguen a esta sección le indican cómo hacer los pasos a mano. Úselas si no puede usar el script.

El script hace estos pasos:

Encuentra la compilación correcta (amd64 o arm64) para su equipo.
Lee cuál es la versión más reciente. Si la aplicación ya tiene esta versión, el script se detiene y no descarga ningún archivo.
Descarga el archivo de imagen más reciente y su archivo de comprobación, y comprueba el archivo de imagen. Si la comprobación falla, el script se detiene y no cambia la aplicación.
En la primera instalación, inicia el contenedor y muestra el enlace con la clave de acceso.
Si la aplicación ya está instalada, la actualiza. Escribe una copia de seguridad del volumen, inicia la versión nueva con el mismo volumen, el mismo puerto y los mismos ajustes, y conserva la imagen anterior.
Si la versión nueva no se inicia, el script inicia otra vez la versión anterior.

Hay dos scripts: install-luca.ps1 para Windows e install-luca.sh para un equipo Mac. Descargue los scripts en ? > Descargas en la aplicación, o desde estos enlaces: install-luca.ps1 (Windows) e install-luca.sh (Mac).

ADVERTENCIA: Mantenga privado el archivo de copia de seguridad. Contiene la clave de acceso, el almacén cifrado de credenciales y la clave de ese almacén. El script escribe el archivo de copia de seguridad en la carpeta actual. Su nombre empieza por luc-analytics-data-backup-.

Usar el script en Windows¶

Instale Docker Desktop (consulte "Instalar Docker Desktop").
Inicie Docker Desktop. Espere hasta que Docker Desktop muestre Engine running (el motor está en ejecución).
Descargue el archivo install-luca.ps1 en su carpeta Descargas.
Abra PowerShell y escriba estos comandos:

cd $HOME\Downloads
powershell -ExecutionPolicy Bypass -File .\install-luca.ps1

Espere hasta que el script muestre is installed, is upgraded o is already up to date (el script muestra sus mensajes en inglés). La descarga puede tardar unos minutos.

Usar el script en un equipo Mac¶

Instale Docker Desktop para Mac (consulte "Instalar Docker Desktop para Mac").
Inicie Docker Desktop. Espere hasta que Docker Desktop muestre Engine running (el motor está en ejecución).
Descargue el archivo install-luca.sh en su carpeta Descargas.
Abra la aplicación Terminal y escriba este comando:

cd ~/Downloads && bash install-luca.sh

Espere hasta que el script muestre is installed, is upgraded o is already up to date (el script muestra sus mensajes en inglés). La descarga puede tardar unos minutos.

Después del script¶

El script abre la aplicación en su navegador. En la primera instalación, también muestra el enlace con la clave de acceso. No dé este enlace a otras personas. Para leer otra vez la clave de acceso, consulte "Abrir la aplicación con la clave de acceso".

El script conserva la imagen de la versión anterior. Para eliminar las imágenes más antiguas cuando actualiza, añada -PruneOld (Windows) o --prune-old (Mac) al comando. Para volver a la versión anterior, añada -Rollback (Windows) o --rollback (Mac) al comando.

Si el script se detiene con un error¶

Mensaje	Causa y acción correctiva
`Docker does not run`	Docker Desktop no se inició. Inicie Docker Desktop y espere hasta que muestre Engine running. Luego haga otra vez el paso.
`checksum mismatch`	El archivo descargado no es correcto. El script no cambió la aplicación. Haga otra vez el paso.
`Could not download`	Asegúrese de que su equipo tiene conexión a internet. O use un archivo de imagen que ya tiene (consulte la sección siguiente).
`Could not read`	El script no puede saber cuál es la versión más reciente. El script no cambió la aplicación. Asegúrese de que su equipo tiene conexión a internet. Luego haga otra vez el paso.
`The download folder changed`	Salió una versión nueva durante la descarga. El script no cambió la aplicación. Haga otra vez el paso.
`docker run failed`	Es posible que el puerto 8000 no esté libre. Añada `-Port 8080` (Windows) o `--port 8080` (Mac) al comando. Luego abra la aplicación en `http://localhost:8080/`.
`ROLLED BACK`	La versión nueva no se inició. La versión anterior funciona otra vez con sus datos. Envíe la salida del script a la persona que le dio la aplicación.

Usar un archivo de imagen que ya tiene¶

Si su equipo no tiene conexión a internet, puede usar un archivo de imagen y su archivo de comprobación que ya tiene. El script comprueba el archivo y luego hace los mismos pasos.

En Windows:

Ponga install-luca.ps1 en la carpeta que tiene el archivo de imagen y el archivo de comprobación.
Haga los pasos 1 a 3 de "Comprobar el archivo de imagen". El comando guarda el nombre del archivo de imagen en $f.
En la misma ventana de PowerShell, escriba este comando:

powershell -ExecutionPolicy Bypass -File .\install-luca.ps1 -ImageFile $f

En un equipo Mac:

Ponga install-luca.sh, el archivo de imagen y el archivo de comprobación en su carpeta Descargas.
Haga los pasos 1 y 2 de "Comprobar el archivo de imagen en un equipo Mac". El comando guarda el nombre del archivo de imagen en $f.
En la misma ventana de Terminal, escriba este comando:

bash install-luca.sh --image-file "$f"

Requisitos del sistema¶

Su portátil con Windows debe tener estos elementos:

Una versión de 64 bits de Windows 10 o de Windows 11.
Un procesador Intel o AMD, o un procesador ARM.
8 GB de memoria (RAM) o más.
Espacio libre en el disco para la imagen, el archivo de imagen, sus datos y las copias de conjuntos de datos que usted descarga. La imagen puede usar hasta 3.5 GB.
Docker Desktop para Windows con el back end WSL 2.

Usted no necesita una cuenta de Docker.

Instalar Docker Desktop¶

Descargue Docker Desktop para Windows de docker.com.
Inicie el instalador.
No cambie los valores predeterminados en el instalador.
Asegúrese de que selecciona Use WSL 2 instead of Hyper-V (usar WSL 2 en lugar de Hyper-V).
Si el instalador le indica que reinicie Windows, reinicie Windows.
Inicie Docker Desktop.
Espere hasta que Docker Desktop muestre Engine running (el motor está en ejecución).
Abra PowerShell y escriba este comando:

docker version

Asegúrese de que la salida tiene una parte Server (servidor). Si la parte Server no está, el motor de Docker no se inició.

Seleccionar la compilación correcta (amd64 o arm64)¶

Usted recibe el archivo de imagen en dos compilaciones. La compilación debe corresponder al procesador de su portátil:

Compilación	Procesador	Archivo de imagen	Archivo de comprobación
amd64	Intel o AMD	`luc-analytics-beta-...-amd64.tar.gz`	`luc-analytics-beta-...-amd64.tar.gz.sha256`
arm64	ARM (por ejemplo, Snapdragon)	`luc-analytics-beta-...-arm64.tar.gz`	`luc-analytics-beta-...-arm64.tar.gz.sha256`

En el nombre del archivo, la parte entre beta- y la compilación es el commit, por ejemplo 105ef19. El commit es un código corto que identifica la versión de la aplicación. Usted no escribe el commit. Los comandos de esta guía lo encuentran en el nombre del archivo.

Cada compilación tiene una carpeta de descarga. La carpeta tiene el archivo de imagen más reciente y su archivo de comprobación. Descargue los dos archivos de su compilación en la misma carpeta. Cuando la aplicación está en ejecución, puede abrir las carpetas de descarga desde la aplicación: pulse ? en la barra superior y luego pulse Descargas. Para la primera instalación, pida los enlaces a la persona que le dio la aplicación.

En PowerShell, escriba este comando:

$env:PROCESSOR_ARCHITECTURE

Lea la salida. Si la salida es AMD64, use la compilación amd64. Si la salida es ARM64, use la compilación arm64.
Asegúrese de que tiene el archivo de imagen y el archivo de comprobación de esa compilación.

NOTA: Si no tiene los archivos de su compilación, descárguelos de la carpeta de descarga de su compilación (? > Descargas en la aplicación). O pida los archivos a la persona que le dio la aplicación.

Comprobar el archivo de imagen¶

NOTA: Haga los pasos de esta sección y de "Cargar la imagen" en la misma ventana de PowerShell. Los comandos guardan el nombre del archivo en $f.

Abra PowerShell en la carpeta que tiene el archivo de imagen y el archivo de comprobación.
Escriba este comando. Encuentra el archivo de imagen para el procesador de su portátil y muestra su nombre:

$f = (Get-ChildItem ".\luc-analytics-beta-*-$($env:PROCESSOR_ARCHITECTURE.ToLower()).tar.gz" | Sort-Object LastWriteTime | Select-Object -Last 1).Name; $f

Asegúrese de que la salida es el nombre de su archivo de imagen. Si la carpeta tiene más de un archivo de imagen, el comando usa el archivo más reciente.
Escriba este comando:

(Get-FileHash $f -Algorithm SHA256).Hash -eq (Get-Content "$f.sha256").Split(' ')[0]

Lea la salida. Si la salida es True, el archivo es correcto.

ADVERTENCIA: No use el archivo de imagen si la salida es False. El archivo está dañado, o no es el archivo correcto. Descargue otra vez el archivo de imagen y el archivo de comprobación.

Cargar la imagen¶

Escriba este comando:

docker load -i $f

La salida muestra la línea Loaded image: luc-analytics:beta-....
Dé a la imagen el nombre corto luc-analytics. Este comando obtiene el commit del nombre del archivo:

docker tag ("luc-analytics:" + ($f -replace '^luc-analytics-(beta-[0-9a-f]+)-.*$','$1')) luc-analytics

Para ver la compilación de la imagen, escriba este comando:

docker image inspect luc-analytics --format "{{.Architecture}}"

Asegúrese de que la salida (amd64 o arm64) corresponde a la compilación que encontró antes.

Después de cargar la imagen, puede eliminar el archivo de imagen. Guarde el archivo si quiere cargar la imagen otra vez.

Instalar en un equipo Mac¶

En un equipo Mac, haga los pasos de esta sección en lugar de las secciones desde "Requisitos del sistema" hasta "Cargar la imagen". Use la aplicación Terminal para todos los comandos de esta guía. Los comandos docker son los mismos que en PowerShell.

Requisitos del sistema en un equipo Mac¶

Su equipo Mac debe tener estos elementos:

Una versión de macOS que la versión actual de Docker Desktop para Mac admite.
Un chip de Apple (M1 o posterior), o un procesador Intel.
8 GB de memoria (RAM) o más.
Espacio libre en el disco para la imagen, el archivo de imagen, sus datos y las copias de conjuntos de datos que usted descarga. La imagen puede usar hasta 3.5 GB.

Instalar Docker Desktop para Mac¶

Busque el chip de su equipo Mac. Abra el menú Apple y seleccione About This Mac (Acerca de este Mac).
Lea la línea Chip o Processor (procesador):
Si la línea empieza por Apple M, su equipo Mac tiene un chip de Apple. Use la compilación arm64 de la aplicación.
Si la línea contiene Intel, su equipo Mac tiene un procesador Intel. Use la compilación amd64 de la aplicación.
Descargue Docker Desktop para Mac de docker.com. Seleccione la descarga para su chip: chip de Apple o chip de Intel.
Abra el archivo descargado Docker.dmg.
Mueva el icono Docker a la carpeta Applications (Aplicaciones).
Inicie Docker desde la carpeta Applications.
Acepte las condiciones del acuerdo de servicio. No cambie los ajustes recomendados.
Espere hasta que Docker Desktop muestre Engine running (el motor está en ejecución).
Abra la aplicación Terminal. Está en la carpeta Applications > Utilities (Aplicaciones > Utilidades).
Escriba este comando:
```
docker version
```
Asegúrese de que la salida tiene una parte Server (servidor). Si la parte Server no está, el motor de Docker no se inició.

Comprobar el archivo de imagen en un equipo Mac¶

NOTA: Haga los pasos de esta sección y de "Cargar la imagen en un equipo Mac" en la misma ventana de Terminal. Los comandos guardan el nombre del archivo en $f.

Los comandos siguientes usan la carpeta Downloads (Descargas). Si sus archivos están en otra carpeta, use esa carpeta en lugar de ~/Downloads.

Escriba este comando. Encuentra el archivo de imagen para el chip de su equipo Mac y muestra su nombre:

cd ~/Downloads && a=$(uname -m | sed s/x86_64/amd64/) && f=$(ls -t luc-analytics-beta-*-$a.tar.gz | head -1) && echo $f

Asegúrese de que la salida es el nombre de su archivo de imagen. Si la carpeta tiene más de un archivo de imagen, el comando usa el archivo más reciente.
Escriba este comando:

shasum -a 256 -c "$f.sha256"

Lea la salida. Si la salida es el nombre del archivo y OK, el archivo es correcto.

ADVERTENCIA: No use el archivo de imagen si la salida muestra FAILED. El archivo está dañado, o no es el archivo correcto. Descargue otra vez el archivo de imagen y el archivo de comprobación.

NOTA: Si el comando del paso 1 no encuentra ningún archivo, es posible que Safari abriera el archivo después de la descarga. Entonces la carpeta tiene un archivo .tar, no un archivo .tar.gz. En Safari, vaya a Settings > General (Ajustes > General) y desmarque Open "safe" files after downloading (abrir archivos "seguros" después de descargarlos). Luego descargue los archivos otra vez.

Cargar la imagen en un equipo Mac¶

Escriba este comando:

docker load -i "$f"

La salida muestra la línea Loaded image: luc-analytics:beta-....
Dé a la imagen el nombre corto luc-analytics. Este comando obtiene el commit del nombre del archivo:

docker tag "luc-analytics:$(echo $f | sed -E 's/^luc-analytics-(beta-[0-9a-f]+)-.*$/\1/')" luc-analytics

Para ver la compilación de la imagen, escriba este comando:

docker image inspect luc-analytics --format "{{.Architecture}}"

Asegúrese de que la salida corresponde a su equipo Mac: arm64 para un chip de Apple, amd64 para un procesador Intel.

Luego continúe en "Iniciar el contenedor". Escriba los mismos comandos en Terminal.

Memoria en un equipo Mac¶

Docker Desktop para Mac define la memoria que Docker puede usar. La aplicación necesita 5 GB de memoria o más en Docker. Para cambiar la memoria, haga estos pasos:

En Docker Desktop, vaya a Settings > Resources (Configuración > Recursos).
Defina el límite de memoria en 5 GB o más. Recomendamos de 5 GB a 6 GB en un equipo Mac con 8 GB de memoria.
Pulse Apply & restart (aplicar y reiniciar).

La sección "Ajustes de memoria" de más abajo es solo para Windows. La última parte de esa sección, sobre Configuración > Memoria en la aplicación, también es correcta en un equipo Mac.

Iniciar el contenedor¶

NOTA: Asegúrese de que el puerto 8000 está libre en su portátil. Si el puerto 8000 no está libre, docker run falla. Para la acción correctiva, consulte 07-troubleshooting.md.

Escriba estos comandos:

docker run -d --name luc-analytics -p 127.0.0.1:8000:8000 -v luc-analytics-data:/data luc-analytics
docker logs luc-analytics

El primer comando crea un contenedor con el nombre luc-analytics. Solo los programas de su portátil pueden conectarse a él, en el puerto 8000. El contenedor guarda todos sus datos en un volumen de Docker con el nombre luc-analytics-data.

Después de aproximadamente 40 segundos, la página Containers (contenedores) de Docker Desktop muestra el contenedor como sano (healthy).

El archivo de configuración¶

En el primer inicio, el contenedor crea el archivo de configuración /data/config.yaml en el volumen. Copia el archivo config.example.yaml de la imagen, con dos cambios:

Las cargas de listas están activadas.
Usted puede descargar copias de conjuntos de datos en la carpeta /data/datasets.

El archivo copiado también tiene activado el mapa base Copernicus (CDSE). El mapa base CDSE también necesita un ID de instancia. Para el ID de instancia, consulte 06-settings.md.

El contenedor crea este archivo solo en el primer inicio. Si el archivo /data/config.yaml existe, el contenedor no lo cambia.

Abrir la aplicación con la clave de acceso¶

La aplicación no tiene cuentas de usuario. La aplicación usa una clave de acceso para que otras personas no puedan usarla. La aplicación crea su clave de acceso en el primer inicio y la guarda en el volumen, en el archivo /data/state/access-key. No hay ninguna clave de acceso en la imagen.

ADVERTENCIA: No dé el enlace con la clave de acceso a otras personas. Una persona con el enlace puede usar la aplicación y su credencial de AWS.

En la salida de docker logs luc-analytics, busque esta línea:

serve: open http://localhost:8000/?access_key=... (once per browser).

Copie el enlace completo de esa línea.
Pegue el enlace en la barra de direcciones de su navegador.

La aplicación guarda la clave en una cookie del navegador. Después, la barra de direcciones muestra http://localhost:8000/. Haga estos pasos una vez en cada navegador que usa.

El registro muestra el enlace solo en el primer inicio. Para leer la clave de acceso otra vez (por ejemplo, para un navegador nuevo), haga estos pasos:

Asegúrese de que el contenedor está en ejecución.
Escriba este comando:

docker exec luc-analytics cat /data/state/access-key

Abra http://localhost:8000/?access_key=<key> en su navegador. Use la clave del paso 2 en lugar de <key>.

Detener e iniciar la aplicación¶

Para detener la aplicación, escriba este comando:

docker stop luc-analytics

Para iniciar la aplicación otra vez, escriba este comando:

docker start luc-analytics

También puede usar los botones de detener e iniciar en la página Containers de Docker Desktop. Cuando detiene la aplicación, conserva todos sus datos. La clave de acceso no cambia, por eso el navegador no la pide otra vez.

Iniciar la aplicación después de reiniciar el portátil¶

El contenedor no se inicia automáticamente después de reiniciar Windows o macOS. Haga estos pasos:

Inicie Docker Desktop.
Espere hasta que Docker Desktop muestre Engine running.
Escriba este comando:

docker start luc-analytics

Si quiere que el contenedor se inicie cada vez que se inicia el motor de Docker, escriba este comando una vez:

docker update --restart unless-stopped luc-analytics

Para esto, Docker Desktop también debe iniciarse cuando usted inicia sesión en su equipo. Usted configura esto en la configuración de Docker Desktop.

Actualizar a una imagen nueva¶

Para actualizar con un solo comando, haga otra vez los pasos de "Instalar o actualizar con un solo comando". El script escribe la copia de seguridad por usted. Si no puede usar el script, haga los pasos de esta sección.

Todos sus datos están en el volumen luc-analytics-data. Una actualización conserva el volumen, por eso usted conserva sus listas, resultados, credenciales y clave de acceso. El registro no muestra un enlace nuevo después de la actualización.

En su primer inicio, una versión nueva puede cambiar la base de datos de resultados. Es posible que una versión anterior no pueda leer la base de datos cambiada. Por eso, la copia de seguridad es la única forma de volver a la versión anterior.

ADVERTENCIA: Haga una copia de seguridad del volumen antes de actualizar. Si no tiene una copia de seguridad, no puede volver a la versión anterior.

Lea el registro de cambios (changelog) de la versión nueva.
Detenga el contenedor:

docker stop luc-analytics

Abra PowerShell (en un equipo Mac, Terminal) en la carpeta donde quiere guardar la copia de seguridad.

ADVERTENCIA: Mantenga privado el archivo de copia de seguridad. Contiene la clave de acceso, el almacén cifrado de credenciales y la clave de ese almacén.

Escriba el archivo de copia de seguridad en esa carpeta:

docker run --rm --user 0 --entrypoint tar -v luc-analytics-data:/data -v "${PWD}:/backup" luc-analytics -C /data -czf /backup/luc-analytics-data-backup.tgz .

Asegúrese de que el archivo luc-analytics-data-backup.tgz está en la carpeta.
Haga otra vez los pasos de "Comprobar el archivo de imagen" con el archivo de imagen nuevo. En un equipo Mac, haga los pasos de "Comprobar el archivo de imagen en un equipo Mac".
Haga otra vez los pasos de "Cargar la imagen" en la misma ventana. En un equipo Mac, haga los pasos de "Cargar la imagen en un equipo Mac".
Elimine el contenedor antiguo. Este comando no elimina el volumen:

docker rm luc-analytics

Cree un contenedor nuevo en el mismo volumen:

docker run -d --name luc-analytics -p 127.0.0.1:8000:8000 -v luc-analytics-data:/data luc-analytics

El archivo de configuración después de una actualización¶

La actualización no cambia su archivo /data/config.yaml. La imagen nueva no copia su nuevo config.example.yaml en el volumen. Esto tiene estos resultados:

Un ajuste que está en su archivo conserva su valor antiguo. Un valor predeterminado nuevo de la versión nueva no lo reemplaza.
Un ajuste que no está en su archivo recibe el valor que está integrado en el programa. Este valor puede ser diferente del valor del nuevo config.example.yaml.

Por eso, un valor predeterminado nuevo no entra en una instalación que usted actualiza. Para usar un valor predeterminado nuevo, cambie el ajuste en /data/config.yaml y reinicie el contenedor. Si el ajuste tiene la marca [live] en config.example.yaml, también puede cambiarlo en la página Configuración. El registro de cambios le informa de los ajustes nuevos. Para el archivo de configuración, consulte 06-settings.md.

Eliminar la aplicación y sus datos¶

ADVERTENCIA: Haga una copia de seguridad antes de eliminar el volumen (consulte "Actualizar a una imagen nueva", pasos 2 a 5). Cuando elimina el volumen, borra todas las listas, los resultados, las credenciales guardadas, la clave de acceso y todas las copias descargadas de conjuntos de datos. No puede recuperarlos.

Elimine el contenedor. Los datos se quedan en el volumen:

docker rm -f luc-analytics

Elimine el volumen. Este comando borra todos sus datos:

docker volume rm luc-analytics-data

Elimine la imagen. Este comando elimina la imagen con todos sus nombres:

docker image rm -f $(docker image inspect luc-analytics --format "{{.Id}}")

Para eliminar Docker Desktop, vaya a Settings > Apps (Configuración > Aplicaciones) en Windows. En un equipo Mac, use el procedimiento de desinstalación de la documentación de Docker Desktop.

Ajustes de memoria¶

Con el back end WSL 2, Docker puede usar una parte de la memoria de su portátil. De forma predeterminada, esta parte es aproximadamente la mitad de la memoria. Para ver la memoria que Docker puede usar, escriba este comando:

docker info --format "{{.MemTotal}}"

La salida está en bytes.

La aplicación no usa toda la memoria. Deja libres 3 GB o el 10 % de la memoria, el mayor de los dos valores. El mínimo recomendado para la aplicación es 2 GB. Por eso, Docker debe tener 5 GB de memoria o más. Le recomendamos que dé a Docker de 5 GB a 6 GB en un portátil con 8 GB de memoria.

Para cambiar la memoria que Docker puede usar, haga estos pasos:

Si el archivo C:\Users\<your user name>\.wslconfig no existe, créelo.
Abra el archivo en un editor de texto.
Escriba estas líneas en el archivo:

[wsl2]
memory=6GB

Guarde el archivo.
Cierre Docker Desktop.
Escriba este comando en PowerShell:

wsl --shutdown

Inicie Docker Desktop.

Dentro de Docker Desktop, normalmente la aplicación no puede encontrar el límite de memoria. Si esto ocurre, la aplicación le pide el límite. Haga estos pasos:

En la aplicación, vaya a Configuración > Memoria.
En Límite de memoria del host / VM (GB), escriba la memoria que tiene Docker.

NOTA: Cierre otros programas grandes mientras la aplicación hace un análisis. Estos programas usan memoria que posiblemente necesita la aplicación.

Si la aplicación no responde¶

Para ver los mensajes de la aplicación, escriba este comando:

docker logs luc-analytics

Para ver si el contenedor está en ejecución, escriba este comando:

docker ps -a

Si Docker Desktop no muestra Engine running, haga estos pasos:
Cierre Docker Desktop.
Escriba wsl --shutdown en PowerShell.
Inicie Docker Desktop otra vez.

Para más problemas y sus acciones correctivas, consulte 07-troubleshooting.md.