Install and start the app¶

This page tells you how to install, start, stop, upgrade and remove LUC Analytics (LUCA) on a Windows laptop or a Mac with Docker Desktop.

On a Mac, first do the steps in "Install on a Mac". Then continue at "Start the container".

Install or upgrade with one command¶

The install script is the fastest way to install or upgrade the app. The script does the steps of this page for you. The sections after this section tell you how to do the steps by hand. Use them if you cannot use the script.

The script does these steps:

It finds the correct build (amd64 or arm64) for your computer.
It reads which version is the newest. If the app already has this version, the script stops and does not download a file.
It downloads the newest image file and its check file, and checks the image file. If the check fails, the script stops and does not change the app.
On the first installation, it starts the container and shows the link with the access key.
If the app is installed, it upgrades the app. It writes a backup of the volume, starts the new version with the same volume, port and settings, and keeps the older image.
If the new version does not start, the script starts the older version again.

There are two scripts: install-luca.ps1 for Windows and install-luca.sh for a Mac. Download the scripts from ? > Downloads in the app, or from these links: install-luca.ps1 (Windows) and install-luca.sh (Mac).

WARNING: Keep the backup file private. It contains the access key, the encrypted credential store and the key of that store. The script writes the backup file into the current folder. Its name starts with luc-analytics-data-backup-.

Use the script on Windows¶

Install Docker Desktop (see "Install Docker Desktop").
Start Docker Desktop. Wait until Docker Desktop shows Engine running.
Download the file install-luca.ps1 into your Downloads folder.
Open PowerShell and type these commands:

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

Wait until the script shows is installed, is upgraded or is already up to date. The download can take some minutes.

Use the script on a Mac¶

Install Docker Desktop for Mac (see "Install Docker Desktop for Mac").
Start Docker Desktop. Wait until Docker Desktop shows Engine running.
Download the file install-luca.sh into your Downloads folder.
Open the Terminal app and type this command:

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

Wait until the script shows is installed, is upgraded or is already up to date. The download can take some minutes.

After the script¶

The script opens the app in your browser. On the first installation, it also shows the link with the access key. Do not give this link to other persons. To read the access key again, see "Open the app with the access key".

The script keeps the image of the version before. To remove older images when you upgrade, add -PruneOld (Windows) or --prune-old (Mac) to the command. To go back to the version before, add -Rollback (Windows) or --rollback (Mac) to the command.

If the script stops with an error¶

Message	Cause and corrective action
`Docker does not run`	Docker Desktop did not start. Start Docker Desktop and wait for Engine running. Then do the step again.
`checksum mismatch`	The downloaded file is not correct. The script did not change the app. Do the step again.
`Could not download`	Make sure that your computer is online. Or use an image file that you have (see the next section).
`Could not read`	The script cannot find which version is the newest. The script did not change the app. Make sure that your computer is online. Then do the step again.
`The download folder changed`	A new version came out during the download. The script did not change the app. Do the step again.
`docker run failed`	Port 8000 is possibly not free. Add `-Port 8080` (Windows) or `--port 8080` (Mac) to the command. Then open the app at `http://localhost:8080/`.
`ROLLED BACK`	The new version did not start. The older version runs again with your data. Send the output of the script to the person who gave you the app.

Use an image file that you have¶

If your computer is not online, you can use an image file and its check file that you have. The script checks the file and then does the same steps.

On Windows:

Put install-luca.ps1 into the folder that has the image file and the check file.
Do steps 1 to 3 in "Check the image file". The command keeps the name of the image file in $f.
In the same PowerShell window, type this command:

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

On a Mac:

Put install-luca.sh, the image file and the check file into your Downloads folder.
Do steps 1 and 2 in "Check the image file on a Mac". The command keeps the name of the image file in $f.
In the same Terminal window, type this command:

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

System needs¶

Your Windows laptop must have these items:

A 64-bit version of Windows 10 or Windows 11.
An Intel or AMD processor, or an ARM processor.
8 GB of memory (RAM) or more.
Free disk space for the image, the image file, your data and the dataset copies that you download. The image can use up to 3.5 GB.
Docker Desktop for Windows with the WSL 2 back end.

You do not need a Docker account.

Install Docker Desktop¶

Download Docker Desktop for Windows from docker.com.
Start the installer.
Do not change the default values in the installer.
Make sure that you select Use WSL 2 instead of Hyper-V.
If the installer tells you to restart Windows, restart Windows.
Start Docker Desktop.
Wait until Docker Desktop shows Engine running.
Open PowerShell and type this command:

docker version

Make sure that the output has a Server part. If the Server part is not there, the Docker engine did not start.

Select the correct build (amd64 or arm64)¶

You get the image file in two builds. The build must agree with the processor of your laptop:

Build	Processor	Image file	Check file
amd64	Intel or AMD	`luc-analytics-beta-...-amd64.tar.gz`	`luc-analytics-beta-...-amd64.tar.gz.sha256`
arm64	ARM (for example, Snapdragon)	`luc-analytics-beta-...-arm64.tar.gz`	`luc-analytics-beta-...-arm64.tar.gz.sha256`

In the file name, the part between beta- and the build is the commit, for example 105ef19. The commit is a short code that identifies the version of the app. You do not type the commit. The commands in this guide find it in the file name.

Each build has a download folder. The folder has the newest image file and its check file. Download the two files of your build into the same folder. When the app runs, you can open the download folders from the app: push ? in the top bar, then push Downloads. For the first installation, get the links from the person who gave you the app.

In PowerShell, type this command:

$env:PROCESSOR_ARCHITECTURE

Read the output. If the output is AMD64, use the amd64 build. If the output is ARM64, use the arm64 build.
Make sure that you have the image file and the check file for that build.

NOTE: If you do not have the files for your build, download them from the download folder of your build (? > Downloads in the app). Or ask the person who gave you the app.

Check the image file¶

NOTE: Do the steps in this section and in "Load the image" in the same PowerShell window. The commands keep the file name in $f.

Open PowerShell in the folder that has the image file and the check file.
Type this command. It finds the image file for the processor of your laptop and shows its name:

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

Make sure that the output is the name of your image file. If the folder has more than one image file, the command uses the newest file.
Type this command:

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

Read the output. If the output is True, the file is correct.

WARNING: Do not use the image file if the output is False. The file is damaged, or it is not the correct file. Download the image file and the check file again.

Load the image¶

Type this command:

docker load -i $f

The output shows the line Loaded image: luc-analytics:beta-....
Give the image the short name luc-analytics. This command gets the commit from the file name:

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

To see the build of the image, type this command:

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

Make sure that the output (amd64 or arm64) agrees with the build that you found before.

After you load the image, you can delete the image file. Keep the file if you want to load the image again.

Install on a Mac¶

On a Mac, do the steps in this section in place of the sections from "System needs" to "Load the image". Use the Terminal app for all the commands in this guide. The docker commands are the same as in PowerShell.

System needs on a Mac¶

Your Mac must have these items:

A version of macOS that the current Docker Desktop for Mac supports.
An Apple chip (M1 or later), or an Intel processor.
8 GB of memory (RAM) or more.
Free disk space for the image, the image file, your data and the dataset copies that you download. The image can use up to 3.5 GB.

Install Docker Desktop for Mac¶

Find the chip of your Mac. Open the Apple menu and select About This Mac.
Read the Chip or Processor line:
If the line starts with Apple M, your Mac has an Apple chip. Use the arm64 build of the app.
If the line contains Intel, your Mac has an Intel processor. Use the amd64 build of the app.
Download Docker Desktop for Mac from docker.com. Select the download for your chip: Apple chip or Intel chip.
Open the downloaded file Docker.dmg.
Move the Docker icon into the Applications folder.
Start Docker from the Applications folder.
Accept the terms of the service agreement. Do not change the recommended settings.
Wait until Docker Desktop shows Engine running.
Open the Terminal app. It is in the Applications > Utilities folder.
Type this command:
```
docker version
```
Make sure that the output has a Server part. If the Server part is not there, the Docker engine did not start.

Check the image file on a Mac¶

NOTE: Do the steps in this section and in "Load the image on a Mac" in the same Terminal window. The commands keep the file name in $f.

The commands below use the Downloads folder. If your files are in a different folder, use that folder in place of ~/Downloads.

Type this command. It finds the image file for the chip of your Mac and shows its name:

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

Make sure that the output is the name of your image file. If the folder has more than one image file, the command uses the newest file.
Type this command:

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

Read the output. If the output is the file name and OK, the file is correct.

WARNING: Do not use the image file if the output shows FAILED. The file is damaged, or it is not the correct file. Download the image file and the check file again.

NOTE: If the command in step 1 finds no file, Safari possibly opened the file after the download. Then the folder has a .tar file, not a .tar.gz file. In Safari, go to Settings > General and clear Open "safe" files after downloading. Then download the files again.

Load the image on a Mac¶

Type this command:

docker load -i "$f"

The output shows the line Loaded image: luc-analytics:beta-....
Give the image the short name luc-analytics. This command gets the commit from the file name:

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

To see the build of the image, type this command:

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

Make sure that the output agrees with your Mac: arm64 for an Apple chip, amd64 for an Intel processor.

Then continue at "Start the container". Type the same commands in Terminal.

Memory on a Mac¶

Docker Desktop for Mac sets the memory that Docker can use. The app needs 5 GB of memory or more in Docker. To change the memory, do these steps:

In Docker Desktop, go to Settings > Resources.
Set the memory limit to 5 GB or more. We recommend 5 GB to 6 GB on a Mac with 8 GB of memory.
Push Apply & restart.

The "Memory settings" section below is for Windows only. The last part of that section, about Settings > Memory in the app, is also correct on a Mac.

Start the container¶

NOTE: Make sure that port 8000 is free on your laptop. If port 8000 is not free, docker run fails. For the corrective action, see 07-troubleshooting.md.

Type these commands:

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

The first command makes a container with the name luc-analytics. Only programs on your laptop can connect to it, on port 8000. The container keeps all its data in a Docker volume with the name luc-analytics-data.

After approximately 40 seconds, the Containers page of Docker Desktop shows the container as healthy.

The configuration file¶

On the first start, the container makes the configuration file /data/config.yaml in the volume. It copies the file config.example.yaml from the image, with two changes:

Uploads of lists are on.
You can download dataset copies to the folder /data/datasets.

The copied file also has the Copernicus (CDSE) basemap on. The CDSE basemap also needs an instance ID. For the instance ID, see 06-settings.md.

The container makes this file only on the first start. If the file /data/config.yaml exists, the container does not change it.

Open the app with the access key¶

The app has no user accounts. The app uses an access key so that other persons cannot use it. The app makes its access key on the first start and keeps it in the volume, in the file /data/state/access-key. No access key is in the image.

WARNING: Do not give the link with the access key to other persons. A person with the link can use the app and your AWS credential.

In the output of docker logs luc-analytics, find this line:

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

Copy the full link from that line.
Paste the link into the address bar of your browser.

The app keeps the key in a cookie in the browser. Then the address bar shows http://localhost:8000/. Do these steps one time in each browser that you use.

The log shows the link only on the first start. To read the access key again (for example, for a new browser), do these steps:

Make sure that the container runs.
Type this command:

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

Open http://localhost:8000/?access_key=<key> in your browser. Use the key from step 2 in place of <key>.

Stop and start the app¶

To stop the app, type this command:

docker stop luc-analytics

To start the app again, type this command:

docker start luc-analytics

You can also use the stop and start buttons on the Containers page of Docker Desktop. When you stop the app, you keep all your data. The access key does not change, thus the browser does not ask for it again.

Start the app after you start the laptop again¶

The container does not start automatically after you start Windows or macOS again. Do these steps:

Start Docker Desktop.
Wait until Docker Desktop shows Engine running.
Type this command:

docker start luc-analytics

If you want the container to start each time that the Docker engine starts, type this command one time:

docker update --restart unless-stopped luc-analytics

For this, Docker Desktop must also start when you log in to your computer. You set this in the Docker Desktop settings.

Upgrade to a new image¶

To upgrade with one command, do the steps in "Install or upgrade with one command" again. The script writes the backup for you. If you cannot use the script, do the steps in this section.

All your data is in the volume luc-analytics-data. An upgrade keeps the volume, thus you keep your lists, results, credentials and access key. The log does not show a new link after the upgrade.

On its first start, a new version can change the results database. An older version possibly cannot read the changed database. Thus, the backup is the only way to go back to the older version.

WARNING: Make a backup of the volume before you upgrade. If you do not have a backup, you cannot go back to the older version.

Read the changelog of the new version.
Stop the container:

docker stop luc-analytics

Open PowerShell (on a Mac, Terminal) in the folder where you want to keep the backup.

WARNING: Keep the backup file private. It contains the access key, the encrypted credential store and the key of that store.

Write the backup file to that folder:

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 .

Make sure that the file luc-analytics-data-backup.tgz is in the folder.
Do the steps in "Check the image file" again with the new image file. On a Mac, do the steps in "Check the image file on a Mac".
Do the steps in "Load the image" again in the same window. On a Mac, do the steps in "Load the image on a Mac".
Remove the old container. This command does not remove the volume:

docker rm luc-analytics

Make a new container on the same volume:

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

The configuration file after an upgrade¶

The upgrade does not change your file /data/config.yaml. The new image does not copy its new config.example.yaml into the volume. This has these results:

A setting that is in your file keeps its old value. A new default value in the new version does not replace it.
A setting that is not in your file gets the value that is built into the program. This value can be different from the value in the new config.example.yaml.

Thus, a new default value does not go into an install that you upgrade. To use a new default value, change the setting in /data/config.yaml and restart the container. If the setting has the mark [live] in config.example.yaml, you can also change it on the Settings page. The changelog tells you about new settings. For the configuration file, see 06-settings.md.

Remove the app and its data¶

WARNING: Make a backup before you remove the volume (see "Upgrade to a new image", steps 2 to 5). When you remove the volume, you delete all lists, results, saved credentials, the access key and all downloaded dataset copies. You cannot get them back.

Remove the container. The data stays in the volume:

docker rm -f luc-analytics

Remove the volume. This command deletes all your data:

docker volume rm luc-analytics-data

Remove the image. This command removes the image with all its names:

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

To remove Docker Desktop, go to Settings > Apps in Windows. On a Mac, use the uninstall procedure in the Docker Desktop documentation.

Memory settings¶

With the WSL 2 back end, Docker can use a part of the memory of your laptop. By default, this part is approximately half of the memory. To see the memory that Docker can use, type this command:

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

The output is in bytes.

The app does not use all of the memory. It leaves 3 GB or 10% of the memory free, the larger of the two. The recommended minimum for the app is 2 GB. Thus, Docker must have 5 GB of memory or more. We recommend that you give Docker 5 GB to 6 GB on a laptop with 8 GB of memory.

To change the memory that Docker can use, do these steps:

If the file C:\Users\<your user name>\.wslconfig does not exist, make it.
Open the file in a text editor.
Write these lines in the file:

[wsl2]
memory=6GB

Save the file.
Quit Docker Desktop.
Type this command in PowerShell:

wsl --shutdown

Start Docker Desktop.

Inside Docker Desktop, the app usually cannot find the memory limit. If this occurs, the app asks you for the limit. Do these steps:

In the app, go to Settings > Memory.
In Host / VM memory limit (GB), type the memory that Docker has.

NOTE: Close other large programs while the app does an analysis. These programs use memory that the app possibly needs.

If the app does not answer¶

To see the messages from the app, type this command:

docker logs luc-analytics

To see if the container runs, type this command:

docker ps -a

If Docker Desktop does not show Engine running, do these steps:
Quit Docker Desktop.
Type wsl --shutdown in PowerShell.
Start Docker Desktop again.

For more problems and their corrective actions, see 07-troubleshooting.md.