Instalar e iniciar o aplicativo¶

Esta página explica como instalar, iniciar, parar, atualizar e remover o LUC Analytics (LUCA) em um laptop com Windows ou em um Mac, com o Docker Desktop.

Em um Mac, faça primeiro as etapas de "Instalar em um Mac". Depois continue em "Iniciar o contêiner".

Instalar ou atualizar com um só comando¶

O script de instalação é a forma mais rápida de instalar ou atualizar o aplicativo. O script faz por você as etapas desta página. As seções depois desta seção explicam como fazer as etapas manualmente. Use-as se você não puder usar o script.

O script faz estas etapas:

Ele encontra a compilação correta (amd64 ou arm64) para o seu computador.
Ele lê qual é a versão mais recente. Se o aplicativo já tem essa versão, o script para e não baixa nenhum arquivo.
Ele baixa o arquivo de imagem mais recente e o seu arquivo de verificação, e verifica o arquivo de imagem. Se a verificação falhar, o script para e não altera o aplicativo.
Na primeira instalação, ele inicia o contêiner e mostra o link com a chave de acesso.
Se o aplicativo já estiver instalado, ele o atualiza. Ele grava um backup do volume, inicia a nova versão com o mesmo volume, a mesma porta e as mesmas configurações, e mantém a imagem mais antiga.
Se a nova versão não iniciar, o script inicia novamente a versão mais antiga.

Há dois scripts: install-luca.ps1 para Windows e install-luca.sh para um Mac. Baixe os scripts em ? > Baixar o aplicativo no aplicativo, ou destes links: install-luca.ps1 (Windows) e install-luca.sh (Mac).

AVISO: Mantenha o arquivo de backup privado. Ele contém a chave de acesso, o armazenamento criptografado de credenciais e a chave desse armazenamento. O script grava o arquivo de backup na pasta atual. O nome dele começa com luc-analytics-data-backup-.

Usar o script no Windows¶

Instale o Docker Desktop (consulte "Instalar o Docker Desktop").
Inicie o Docker Desktop. Aguarde até que o Docker Desktop mostre Engine running (mecanismo em execução).
Baixe o arquivo install-luca.ps1 na sua pasta Downloads.
Abra o PowerShell e digite estes comandos:

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

Aguarde até que o script mostre is installed, is upgraded ou is already up to date (o script mostra as mensagens em inglês). O download pode levar alguns minutos.

Usar o script em um Mac¶

Instale o Docker Desktop para Mac (consulte "Instalar o Docker Desktop para Mac").
Inicie o Docker Desktop. Aguarde até que o Docker Desktop mostre Engine running (mecanismo em execução).
Baixe o arquivo install-luca.sh na sua pasta Downloads.
Abra o aplicativo Terminal e digite este comando:

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

Aguarde até que o script mostre is installed, is upgraded ou is already up to date (o script mostra as mensagens em inglês). O download pode levar alguns minutos.

Depois do script¶

O script abre o aplicativo no seu navegador. Na primeira instalação, ele também mostra o link com a chave de acesso. Não dê este link a outras pessoas. Para ler novamente a chave de acesso, consulte "Abrir o aplicativo com a chave de acesso".

O script mantém a imagem da versão anterior. Para remover imagens mais antigas quando você atualizar, adicione -PruneOld (Windows) ou --prune-old (Mac) ao comando. Para voltar à versão anterior, adicione -Rollback (Windows) ou --rollback (Mac) ao comando.

Se o script parar com um erro¶

Mensagem	Causa e ação corretiva
`Docker does not run`	O Docker Desktop não iniciou. Inicie o Docker Desktop e aguarde Engine running. Depois faça a etapa novamente.
`checksum mismatch`	O arquivo baixado não está correto. O script não alterou o aplicativo. Faça a etapa novamente.
`Could not download`	Verifique se o seu computador está conectado à internet. Ou use um arquivo de imagem que você já tem (consulte a próxima seção).
`Could not read`	O script não consegue saber qual é a versão mais recente. O script não alterou o aplicativo. Verifique se o seu computador está conectado à internet. Depois, faça a etapa novamente.
`The download folder changed`	Uma versão nova saiu durante o download. O script não alterou o aplicativo. Faça a etapa novamente.
`docker run failed`	A porta 8000 possivelmente não está livre. Adicione `-Port 8080` (Windows) ou `--port 8080` (Mac) ao comando. Depois abra o aplicativo em `http://localhost:8080/`.
`ROLLED BACK`	A nova versão não iniciou. A versão mais antiga funciona novamente com os seus dados. Envie a saída do script à pessoa que lhe deu o aplicativo.

Usar um arquivo de imagem que você já tem¶

Se o seu computador não estiver conectado à internet, você pode usar um arquivo de imagem e o seu arquivo de verificação que você já tem. O script verifica o arquivo e depois faz as mesmas etapas.

No Windows:

Coloque install-luca.ps1 na pasta que tem o arquivo de imagem e o arquivo de verificação.
Faça as etapas 1 a 3 de "Verificar o arquivo de imagem". O comando guarda o nome do arquivo de imagem em $f.
Na mesma janela do PowerShell, digite este comando:

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

Em um Mac:

Coloque install-luca.sh, o arquivo de imagem e o arquivo de verificação na sua pasta Downloads.
Faça as etapas 1 e 2 de "Verificar o arquivo de imagem em um Mac". O comando guarda o nome do arquivo de imagem em $f.
Na mesma janela do Terminal, digite este comando:

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

Requisitos do sistema¶

O seu laptop com Windows deve ter estes itens:

Uma versão de 64 bits do Windows 10 ou do Windows 11.
Um processador Intel ou AMD, ou um processador ARM.
8 GB de memória (RAM) ou mais.
Espaço livre em disco para a imagem, o arquivo de imagem, os seus dados e as cópias de conjuntos de dados que você baixar. A imagem pode usar até 3.5 GB.
Docker Desktop para Windows com o back end WSL 2.

Você não precisa de uma conta Docker.

Instalar o Docker Desktop¶

Baixe o Docker Desktop para Windows em docker.com.
Inicie o instalador.
Não altere os valores padrão no instalador.
Verifique se você selecionou Use WSL 2 instead of Hyper-V (usar o WSL 2 em vez do Hyper-V).
Se o instalador pedir para reiniciar o Windows, reinicie o Windows.
Inicie o Docker Desktop.
Aguarde até que o Docker Desktop mostre Engine running (mecanismo em execução).
Abra o PowerShell e digite este comando:

docker version

Verifique se a saída tem uma parte Server (servidor). Se a parte Server não estiver lá, o mecanismo do Docker não iniciou.

Selecionar a compilação correta (amd64 ou arm64)¶

Você recebe o arquivo de imagem em duas compilações. A compilação deve corresponder ao processador do seu laptop:

Compilação	Processador	Arquivo de imagem	Arquivo de verificação
amd64	Intel ou AMD	`luc-analytics-beta-...-amd64.tar.gz`	`luc-analytics-beta-...-amd64.tar.gz.sha256`
arm64	ARM (por exemplo, Snapdragon)	`luc-analytics-beta-...-arm64.tar.gz`	`luc-analytics-beta-...-arm64.tar.gz.sha256`

No nome do arquivo, a parte entre beta- e a compilação é o commit, por exemplo 105ef19. O commit é um código curto que identifica a versão do aplicativo. Você não digita o commit. Os comandos deste guia o encontram no nome do arquivo.

Cada compilação tem uma pasta de download. A pasta tem o arquivo de imagem mais recente e o seu arquivo de verificação. Baixe os dois arquivos da sua compilação para a mesma pasta. Quando o aplicativo está em execução, você pode abrir as pastas de download no aplicativo: pressione ? na barra superior e depois pressione Baixar o aplicativo. Para a primeira instalação, peça os links à pessoa que lhe deu o aplicativo.

No PowerShell, digite este comando:

$env:PROCESSOR_ARCHITECTURE

Leia a saída. Se a saída for AMD64, use a compilação amd64. Se a saída for ARM64, use a compilação arm64.
Verifique se você tem o arquivo de imagem e o arquivo de verificação dessa compilação.

NOTA: Se você não tiver os arquivos da sua compilação, baixe-os da pasta de download da sua compilação (? > Baixar o aplicativo no aplicativo). Ou peça os arquivos à pessoa que lhe deu o aplicativo.

Verificar o arquivo de imagem¶

NOTA: Faça as etapas desta seção e de "Carregar a imagem" na mesma janela do PowerShell. Os comandos guardam o nome do arquivo em $f.

Abra o PowerShell na pasta que tem o arquivo de imagem e o arquivo de verificação.
Digite este comando. Ele encontra o arquivo de imagem para o processador do seu laptop e mostra o seu nome:

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

Verifique se a saída é o nome do seu arquivo de imagem. Se a pasta tiver mais de um arquivo de imagem, o comando usa o arquivo mais recente.
Digite este comando:

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

Leia a saída. Se a saída for True, o arquivo está correto.

AVISO: Não use o arquivo de imagem se a saída for False. O arquivo está danificado, ou não é o arquivo correto. Baixe novamente o arquivo de imagem e o arquivo de verificação.

Carregar a imagem¶

Digite este comando:

docker load -i $f

A saída mostra a linha Loaded image: luc-analytics:beta-....
Dê à imagem o nome curto luc-analytics. Este comando obtém o commit do nome do arquivo:

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

Para ver a compilação da imagem, digite este comando:

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

Verifique se a saída (amd64 ou arm64) corresponde à compilação que você encontrou antes.

Depois de carregar a imagem, você pode excluir o arquivo de imagem. Guarde o arquivo se quiser carregar a imagem novamente.

Instalar em um Mac¶

Em um Mac, faça as etapas desta seção no lugar das seções de "Requisitos do sistema" até "Carregar a imagem". Use o aplicativo Terminal para todos os comandos deste guia. Os comandos docker são os mesmos do PowerShell.

Requisitos do sistema em um Mac¶

O seu Mac deve ter estes itens:

Uma versão do macOS que a versão atual do Docker Desktop para Mac suporta.
Um chip da Apple (M1 ou posterior), ou um processador Intel.
8 GB de memória (RAM) ou mais.
Espaço livre em disco para a imagem, o arquivo de imagem, os seus dados e as cópias de conjuntos de dados que você baixa. A imagem pode usar até 3,5 GB.

Instalar o Docker Desktop para Mac¶

Encontre o chip do seu Mac. Abra o menu Apple e selecione About This Mac (Sobre Este Mac).
Leia a linha Chip ou Processor (processador):
Se a linha começar com Apple M, o seu Mac tem um chip da Apple. Use a compilação arm64 do aplicativo.
Se a linha contiver Intel, o seu Mac tem um processador Intel. Use a compilação amd64 do aplicativo.
Baixe o Docker Desktop para Mac em docker.com. Selecione o download para o seu chip: chip da Apple ou chip da Intel.
Abra o arquivo baixado Docker.dmg.
Mova o ícone Docker para a pasta Applications (Aplicativos).
Inicie o Docker a partir da pasta Applications.
Aceite os termos do contrato de serviço. Não altere as configurações recomendadas.
Aguarde até que o Docker Desktop mostre Engine running (o mecanismo está em execução).
Abra o aplicativo Terminal. Ele está na pasta Applications > Utilities (Aplicativos > Utilitários).
Digite este comando:
```
docker version
```
Verifique se a saída tem uma parte Server (servidor). Se a parte Server não estiver lá, o mecanismo do Docker não iniciou.

Verificar o arquivo de imagem em um Mac¶

NOTA: Faça as etapas desta seção e de "Carregar a imagem em um Mac" na mesma janela do Terminal. Os comandos guardam o nome do arquivo em $f.

Os comandos abaixo usam a pasta Downloads (Transferências). Se os seus arquivos estiverem em outra pasta, use essa pasta no lugar de ~/Downloads.

Digite este comando. Ele encontra o arquivo de imagem para o chip do seu Mac e mostra o seu nome:

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

Verifique se a saída é o nome do seu arquivo de imagem. Se a pasta tiver mais de um arquivo de imagem, o comando usa o arquivo mais recente.
Digite este comando:

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

Leia a saída. Se a saída for o nome do arquivo e OK, o arquivo está correto.

AVISO: Não use o arquivo de imagem se a saída mostrar FAILED. O arquivo está danificado, ou não é o arquivo correto. Baixe novamente o arquivo de imagem e o arquivo de verificação.

NOTA: Se o comando da etapa 1 não encontrar nenhum arquivo, é possível que o Safari tenha aberto o arquivo depois do download. Então a pasta tem um arquivo .tar, e não um arquivo .tar.gz. No Safari, vá para Settings > General (Ajustes > Geral) e desmarque Open "safe" files after downloading (abrir arquivos "seguros" após o download). Depois baixe os arquivos novamente.

Carregar a imagem em um Mac¶

Digite este comando:

docker load -i "$f"

A saída mostra a linha Loaded image: luc-analytics:beta-....
Dê à imagem o nome curto luc-analytics. Este comando obtém o commit do nome do arquivo:

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

Para ver a compilação da imagem, digite este comando:

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

Verifique se a saída corresponde ao seu Mac: arm64 para um chip da Apple, amd64 para um processador Intel.

Depois continue em "Iniciar o contêiner". Digite os mesmos comandos no Terminal.

Memória em um Mac¶

O Docker Desktop para Mac define a memória que o Docker pode usar. O aplicativo precisa de 5 GB de memória ou mais no Docker. Para alterar a memória, faça estas etapas:

No Docker Desktop, vá para Settings > Resources (Configurações > Recursos).
Defina o limite de memória em 5 GB ou mais. Recomendamos de 5 GB a 6 GB em um Mac com 8 GB de memória.
Pressione Apply & restart (aplicar e reiniciar).

A seção "Configurações de memória" abaixo é somente para Windows. A última parte dessa seção, sobre Configurações > Memória no aplicativo, também está correta em um Mac.

Iniciar o contêiner¶

NOTA: Verifique se a porta 8000 está livre no seu laptop. Se a porta 8000 não estiver livre, docker run falha. Para a ação corretiva, consulte 07-troubleshooting.md.

Digite estes 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

O primeiro comando cria um contêiner com o nome luc-analytics. Somente programas do seu laptop podem se conectar a ele, na porta 8000. O contêiner guarda todos os seus dados em um volume Docker com o nome luc-analytics-data.

Depois de aproximadamente 40 segundos, a página Containers (contêineres) do Docker Desktop mostra o contêiner como íntegro (healthy).

O arquivo de configuração¶

Na primeira inicialização, o contêiner cria o arquivo de configuração /data/config.yaml no volume. Ele copia o arquivo config.example.yaml da imagem, com duas alterações:

Os envios de listas estão ativados.
Você pode baixar cópias de conjuntos de dados para a pasta /data/datasets.

O arquivo copiado também tem o mapa base Copernicus (CDSE) ativado. O mapa base CDSE também precisa de um ID da instância. Para o ID da instância, consulte 06-settings.md.

O contêiner cria este arquivo somente na primeira inicialização. Se o arquivo /data/config.yaml existir, o contêiner não o altera.

Abrir o aplicativo com a chave de acesso¶

O aplicativo não tem contas de usuário. O aplicativo usa uma chave de acesso para que outras pessoas não possam usá-lo. O aplicativo cria a sua chave de acesso na primeira inicialização e a guarda no volume, no arquivo /data/state/access-key. Não há chave de acesso na imagem.

AVISO: Não dê o link com a chave de acesso a outras pessoas. Uma pessoa com o link pode usar o aplicativo e a sua credencial AWS.

Na saída de docker logs luc-analytics, encontre esta linha:

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

Copie o link completo dessa linha.
Cole o link na barra de endereço do seu navegador.

O aplicativo guarda a chave em um cookie no navegador. Depois, a barra de endereço mostra http://localhost:8000/. Faça estas etapas uma vez em cada navegador que você usar.

O log mostra o link somente na primeira inicialização. Para ler a chave de acesso novamente (por exemplo, para um novo navegador), faça estas etapas:

Verifique se o contêiner está em execução.
Digite este comando:

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

Abra http://localhost:8000/?access_key=<key> no seu navegador. Use a chave da etapa 2 no lugar de <key>.

Parar e iniciar o aplicativo¶

Para parar o aplicativo, digite este comando:

docker stop luc-analytics

Para iniciar o aplicativo novamente, digite este comando:

docker start luc-analytics

Você também pode usar os botões de parar e iniciar na página Containers (contêineres) do Docker Desktop. Quando você para o aplicativo, você mantém todos os seus dados. A chave de acesso não muda, portanto o navegador não pede a chave novamente.

Iniciar o aplicativo depois de reiniciar o laptop¶

O contêiner não inicia automaticamente depois que você reinicia o Windows ou o macOS. Faça estas etapas:

Inicie o Docker Desktop.
Aguarde até que o Docker Desktop mostre Engine running.
Digite este comando:

docker start luc-analytics

Se você quiser que o contêiner inicie cada vez que o mecanismo do Docker iniciar, digite este comando uma vez:

docker update --restart unless-stopped luc-analytics

Para isso, o Docker Desktop também deve iniciar quando você faz login no seu computador. Você define isso nas configurações do Docker Desktop.

Atualizar para uma nova imagem¶

Para atualizar com um só comando, faça novamente as etapas de "Instalar ou atualizar com um só comando". O script grava o backup para você. Se você não puder usar o script, faça as etapas desta seção.

Todos os seus dados estão no volume luc-analytics-data. Uma atualização mantém o volume, portanto você mantém as suas listas, resultados, credenciais e chave de acesso. O log não mostra um novo link depois da atualização.

Na primeira inicialização, uma nova versão pode alterar o banco de dados de resultados. Uma versão mais antiga possivelmente não consegue ler o banco de dados alterado. Portanto, o backup é a única forma de voltar à versão mais antiga.

AVISO: Faça um backup do volume antes de atualizar. Se você não tiver um backup, não poderá voltar à versão mais antiga.

Leia o registro de alterações (changelog) da nova versão.
Pare o contêiner:

docker stop luc-analytics

Abra o PowerShell (em um Mac, o Terminal) na pasta onde você quer guardar o backup.

AVISO: Mantenha o arquivo de backup privado. Ele contém a chave de acesso, o armazenamento criptografado de credenciais e a chave desse armazenamento.

Grave o arquivo de backup nessa pasta:

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 .

Verifique se o arquivo luc-analytics-data-backup.tgz está na pasta.
Faça novamente as etapas de "Verificar o arquivo de imagem" com o novo arquivo de imagem. Em um Mac, faça as etapas de "Verificar o arquivo de imagem em um Mac".
Faça novamente as etapas de "Carregar a imagem" na mesma janela. Em um Mac, faça as etapas de "Carregar a imagem em um Mac".
Remova o contêiner antigo. Este comando não remove o volume:

docker rm luc-analytics

Crie um novo contêiner no mesmo volume:

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

O arquivo de configuração depois de uma atualização¶

A atualização não altera o seu arquivo /data/config.yaml. A nova imagem não copia o seu novo config.example.yaml para o volume. Isso tem estes resultados:

Uma configuração que está no seu arquivo mantém o valor antigo. Um novo valor padrão na nova versão não a substitui.
Uma configuração que não está no seu arquivo recebe o valor que está no código do programa. Este valor pode ser diferente do valor no novo config.example.yaml.

Portanto, um novo valor padrão não entra em uma instalação que você atualiza. Para usar um novo valor padrão, altere a configuração em /data/config.yaml e reinicie o contêiner. Se a configuração tiver a marca [live] em config.example.yaml, você também pode alterá-la na página Configurações. O registro de alterações informa as novas configurações. Para o arquivo de configuração, consulte 06-settings.md.

Remover o aplicativo e os seus dados¶

AVISO: Faça um backup antes de remover o volume (consulte "Atualizar para uma nova imagem", etapas 2 a 5). Quando você remove o volume, você exclui todas as listas, resultados, credenciais salvas, a chave de acesso e todas as cópias de conjuntos de dados baixadas. Você não pode recuperá-los.

Remova o contêiner. Os dados ficam no volume:

docker rm -f luc-analytics

Remova o volume. Este comando exclui todos os seus dados:

docker volume rm luc-analytics-data

Remova a imagem. Este comando remove a imagem com todos os seus nomes:

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

Para remover o Docker Desktop, vá para Settings > Apps (Configurações > Aplicativos) no Windows. Em um Mac, use o procedimento de desinstalação da documentação do Docker Desktop.

Configurações de memória¶

Com o back end WSL 2, o Docker pode usar uma parte da memória do seu laptop. Por padrão, essa parte é aproximadamente metade da memória. Para ver a memória que o Docker pode usar, digite este comando:

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

A saída é em bytes.

O aplicativo não usa toda a memória. Ele deixa livres 3 GB ou 10% da memória, o maior dos dois valores. O mínimo recomendado para o aplicativo é 2 GB. Portanto, o Docker deve ter 5 GB de memória ou mais. Recomendamos que você dê ao Docker de 5 GB a 6 GB em um laptop com 8 GB de memória.

Para alterar a memória que o Docker pode usar, faça estas etapas:

Se o arquivo C:\Users\<your user name>\.wslconfig não existir, crie-o.
Abra o arquivo em um editor de texto.
Escreva estas linhas no arquivo:

[wsl2]
memory=6GB

Salve o arquivo.
Feche o Docker Desktop.
Digite este comando no PowerShell:

wsl --shutdown

Inicie o Docker Desktop.

Dentro do Docker Desktop, o aplicativo geralmente não consegue encontrar o limite de memória. Se isso ocorrer, o aplicativo pede o limite a você. Faça estas etapas:

No aplicativo, vá para Configurações > Memória.
Em Limite de memória do host / VM (GB), digite a memória que o Docker tem.

NOTA: Feche outros programas grandes enquanto o aplicativo faz uma análise. Esses programas usam memória de que o aplicativo possivelmente precisa.

Se o aplicativo não responder¶

Para ver as mensagens do aplicativo, digite este comando:

docker logs luc-analytics

Para ver se o contêiner está em execução, digite este comando:

docker ps -a

Se o Docker Desktop não mostrar Engine running, faça estas etapas:
Feche o Docker Desktop.
Digite wsl --shutdown no PowerShell.
Inicie o Docker Desktop novamente.

Para mais problemas e as ações corretivas, consulte 07-troubleshooting.md.