Settings¶

This page tells you about each section of the Settings page and about the configuration file.

To open the page, push ⚙ Settings in the top bar. The page has these sections, from top to bottom:

Credentials
Dataset sources
Dataset versions and local data (with Map visualizations in it)
Memory

The language selector is not on the Settings page. It is in the top bar. Refer to Language.

Credentials¶

The Credentials section has one card for each credential:

Card title	Credential	Fields on the card
AWS (S3 datasets)	One AWS key pair. All the S3 dataset sources use this one key pair.	Access key ID, Secret access key
Planet	The Planet basemap key	Username, API key
Google Maps	The Google Maps basemap key	API key
Copernicus (CDSE)	The Copernicus (CDSE) basemap instance ID	Instance ID

Each card has a line In use from: that tells you where the credential in use comes from. The possible values are Environment, Docker secret, Credential Manager, Encrypted store and Not set.

A card with a secret field (Secret access key or API key) also shows Saved or Not saved. The secret field is always empty, also after you save. The app never sends a saved secret back to the browser.

The Access key ID, Username and Instance ID fields are not secrets. These fields show the value that the encrypted store holds.

Where to get each value¶

AWS (S3 datasets): Get an access key ID and a secret access key for an AWS account that you control. The AWS account pays for all the dataset reads. Refer to Dataset sources.
Planet: Get the API key and the username from your Planet account.
Google Maps: Get an API key for Google Maps map tiles from your Google account.
Copernicus (CDSE): Get the instance ID from your Copernicus Data Space dashboard. The instance ID has 8 to 64 characters: letters, digits and hyphens only.

Add or change an AWS key¶

In the AWS (S3 datasets) card, type the key ID in Access key ID.
Type the secret in Secret access key.
Push Check credentials.
Make sure that the result line starts with "Key" and says "is valid".
Push Save.

NOTE: Check credentials is free. It asks AWS STS only if the key pair is valid. It does not read a bucket.

NOTE: You cannot push Save until the key pair passes Check credentials. If you change a field after the check, you must do the check again. The app shows "Check the credentials first. A key pair that failed the check is never saved."

To check the AWS key that is in use now, keep Secret access key empty and do not change Access key ID. Then push Check credentials. If you type only one of the two values, the app shows "Enter both the access key ID and the secret access key, or neither."

Results of Check credentials¶

Result	What it tells you	What to do
"Key ... is valid: ..."	AWS accepted the key pair. The line shows a part of the key, the AWS identity and the last 4 digits of the AWS account.	Push Save if you typed a new pair.
"AWS rejected this credential ..."	The key ID or the secret is wrong, or the key is not active.	Type the two values again, then push Check credentials.
"No AWS credential is entered or saved."	No key pair is typed or saved.	Type the key ID and the secret.
"A stored credential exists but could not be read ..."	The app cannot decrypt the saved key with the active master key.	Type the key ID and the secret again, then save.
"AWS STS could not be reached ..."	A network or endpoint problem. The result does not tell you about the credential.	Do the check again.
"AWS STS did not answer in time."	The check stopped after the time limit. The result does not tell you about the credential.	Do the check again.
"AWS answered ..."	AWS sent a different error code. The line shows the code.	Examine the code.

Add or change a basemap key¶

In the Planet, Google Maps or Copernicus (CDSE) card, type the value. For Planet, type the Username and the API key.
Push Test connection.
Make sure that the result starts with "Connection OK."
Push Save.

NOTE: Test connection sends the typed values to the provider, but it does not save them. You cannot push Save until a test of the same values is successful. The app shows "Test the connection first. A failed connection is never saved."

To test the key that is in use now, keep the card empty. Then push Test connection. The result is one of these:

The source that the app tested. An example is "Tested the credential in use (Environment); nothing was typed on this card."
If the card has no stored value: "Nothing to test: this card is empty and nothing is stored for it."

Results of Test connection for a basemap¶

A successful test starts with "Connection OK." A failed test starts with "Connection failed:". The reason follows.

Result	What it tells you
ok: "The provider accepted this credential."	The key is correct.
unauthorized: "The provider rejected this credential. ..."	The value is wrong, or it does not have permission now.
unreachable: "The provider could not be reached ..."	A network or endpoint problem. It does not tell you about the credential.
timed out: "The provider did not respond within the allowed time. ..."	The provider was too slow, or the app cannot get to it. It does not tell you about the credential.
misconfigured: "The provider is misconfigured on the server, ..."	The server configuration for this provider has a problem. The app did not test the credential.
not configured: "No credential is available to test."	No credential was found.

Where the app keeps credentials¶

The app looks for each credential in 4 places, in this sequence. It uses the first one that it finds:

Environment: environment variables. The names are AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and an optional AWS_SESSION_TOKEN), PLANET_API_KEY (as user:key), GOOGLE_MAPS_API_KEY and CDSE_INSTANCE_ID.
Docker secret: a file with the same name in the Docker secrets folder. The default folder is /run/secrets.
Credential Manager: the Windows Credential Manager. The configuration keys security.credential_manager_names and security.credential_manager_pairs give the target names.
Encrypted store: the credentials that you save on the Settings page.

The encrypted store keeps one file for each credential (<name>.enc.json) in the folder that security.secret_store_dir gives. The default is ./data/secrets.d, relative to the folder of the configuration file. In the Docker image, this folder is /data/data/secrets.d.

A master key encrypts the store. To see where the master key comes from, open Details in the Credentials section. If the master key is a file in the same folder tree as the saved credentials, the app shows a warning. Anyone who can read that folder can then decrypt the credentials.

WARNING: If the master key is a file beside the data, give the key through LUC_ANALYTICS_SECRET_KEY (an environment variable or a Docker secret). A person who can read the key file can read your saved credentials.

Remove a saved credential¶

NOTE: This procedure removes the credential only from the encrypted store. It does not remove an environment variable, a Docker secret or a value in the Windows Credential Manager. You must remove those at their source.

In the Credentials section, open Details.
Find the row of the credential. The Encrypted store column shows Saved, or Saved, not in use (a source above takes precedence).
Push Delete stored.
Read the message, then push OK.
Make sure that the app shows "Stored credential deleted."

CAUTION: You cannot undo a delete. To use the credential again, type it and save it again.

Dataset sources¶

The Dataset sources section tells the app where to read each of the 6 datasets: Pixel area, SBTN natural forests, JRC global forest cover 2020, Disturbance alerts, Tree-cover loss drivers and Tree-cover loss year.

Privacy and cost of reading WRI's bucket¶

The section starts with the notice Privacy and cost of reading WRI's bucket. The notice tells you these facts:

WRI is the source of the datasets. The notice has a link to the WRI Data Explorer page.
When the app reads a dataset from the WRI S3 bucket, WRI records the request in its storage logs. The logs show the parts of the dataset that the app requested. Thus, the logs can show the areas that you analyze. The app never sends your location shapes.
The WRI bucket uses Requester Pays. Each request and each byte that the app transfers goes on your AWS account. This includes each download.

WARNING: All data reads from the WRI bucket are a charge to your AWS account. The app gives the cost as approximately $0.09 for each GB to a computer outside AWS, plus a small fee for each read. These are AWS list prices and they can change.

To prevent these reads, download a copy of each dataset to this computer. After the download, analyses read nothing from WRI.

Dataset cards¶

Each dataset has a card. The card shows a Using: line, a status word and a Change button. The Using: line tells you what the dataset reads now, for example "Using: WRI online, latest — billed per analysis". The status word is Up to date, Newer version available, Not checked or Downloading….

Push See versions to go to the versions of that dataset in Dataset versions and local data.

Change the source of a dataset¶

When you push Change, a dialog opens. The first step asks "Where should dataset come from?". You can select one of 3 choices:

Choice	What it does
WRI online, always the latest	Each analysis reads the dataset from the WRI bucket. Each analysis is a charge to your AWS account.
Download a copy to this computer	The app downloads one copy. You pay one time for the transfer. Then analyses read the copy at no cost.
A folder I already have (advanced)	The app reads a zarr folder that is on this computer already. It never writes to that folder.

The app shows Recommended beside the choice that agrees with how frequently the dataset changes. The app does not change the source itself.

If no AWS key passed the check, the dialog adds the step Add your AWS key. Type the Access key ID and the Secret access key, then push Check this key. You cannot push Next until the key passes the check.

Nothing changes until you push the last button of the dialog. To stop, push Cancel, push ×, or push the Esc key.

Download a copy to this computer¶

WARNING: A download is a charge to your AWS account for the data transfer. Make sure that you accept the cost before you push Start download.

On the dataset card, push Change.
Select Download a copy to this computer.
Push Next.
If the dialog asks "Which version of dataset?", select Latest (needs downloading) or a copy that is on this computer already.
Push Next.
If the dialog asks for an AWS key, type the key and push Check this key. Then push Next.
In Destination, type a folder or push Browse… to select a folder. Refer to The folder browser.
Make sure that the dialog does not show "Not enough free space for this dataset."
Push Next.
Select the box I understand my AWS account is billed for this download.
Push Start download.

If you select a copy that is on this computer already, the dialog asks "Use the copy from date?". Push Use this copy. This makes no request and costs nothing.

Until the download is complete, analyses continue to read the dataset from WRI online. When the download is complete, the dataset reads the local copy.

While a download operates, the card shows Pause, Resume and Stop. Pause keeps the files that arrived. Stop asks you first. If you push Stop and discard, the app deletes the partial copy, and the next download starts again with no files. Push Keep downloading to continue.

The folder browser¶

The Destination and Folder fields have a text box and a Browse… button. You can type a full folder path in the text box.

Push Browse…. The browser shows the Approved download roots.
Select a folder to open it.
To go up one level, push Up.
When the browser shows the correct folder, push Use this folder.
To close the browser without a change, push Close browser.

The browser shows only folders. It never shows files or folders outside an approved root.

Downloads go only into the folders in datasets.download_roots in the configuration file. In the Docker image, the default download root is /data/datasets. If no download root is configured, the browser shows "No download roots are configured on this server (datasets.download_roots), so nothing can be browsed or downloaded."

For A folder I already have (advanced), the browser also shows the folders in datasets.browse_roots with the label "(read only)". You can also type a folder outside the roots. The app then reads the folder but never writes to it.

On a server in WSL, the app reads a Windows path such as D:\data as /mnt/d/data. If that drive is not mounted, the app shows "That drive is not available on this server (it is not mounted)."

The header of Dataset sources¶

Check for updates $ reads the WRI manifest and tells you how many datasets have a newer version. This is one request on the WRI bucket. Thus, it is a small charge to your AWS account.
Update all to latest downloads the newer version of each dataset that reads a local copy. Before the download starts, you must select the box I understand my AWS account is billed for these downloads.
Save this setup keeps the current dataset choices. Go back to this setup puts back a saved setup.

Advanced¶

The Advanced drawer at the bottom of the section is for choices that the dialog cannot make. For each dataset, it shows Source kind, Location, Requester pays, Use manifest path $, Test connection and Save source.

CAUTION: Use the Advanced drawer only if you know the S3 location of the dataset. A wrong location gives wrong results or no results.

Requester pays must be on for the WRI bucket. If it is off, the app does not make a charged request.

Test connection in the Advanced drawer opens the dataset store. This is a charge to your AWS account. A successful result starts with "Connection OK." A failed result starts with "Connection failed:". The reasons are these:

Result	What it tells you
"Connection successful. ..."	The dataset opened and the app can read it.
Requester pays is off	The credential is correct, but Requester pays is off. Turn on Requester pays.
AWS rejected the credential	The key was revoked, is wrong, or does not have permission.
No AWS credential	No AWS key is available. Add a key, then save and test again.
Stored credential cannot be read	The app cannot decrypt the saved key. Type the key again and save.
Not reachable	A network or endpoint problem. It is not a credential problem.
Not a Zarr store	The location is correct, but it has no readable Zarr store.
Timed out	The dataset did not answer in the time limit.
Location not found	Nothing is at that location. Push Use manifest path $.
Region mismatch	The bucket is in a different region. Change `datasets.upstream.region` in `config.yaml`.
AccessDenied	The key is valid but cannot read this bucket. Push Check credentials.
Other AWS error	AWS sent a different error code. The line shows the code.

Dataset versions and local data¶

This section shows each dated version of each dataset, where the app keeps it, and how much disk space it uses.

The app keeps 3 kinds of copy:

Saved automatically: the app makes these copies when you run lists. They count toward the Space limit.
Full download: a copy that you downloaded in Dataset sources. The app never deletes it.
Your own copy: a copy in a folder that you selected. The app never deletes it.

To change the space limit, type a value from 1 to 10000 in Limit for the automatic cache (GB), then push Save limit. The default is 50 GB.

WARNING: If the new limit is less than the space in use, the app deletes older saved layers immediately. If a later run needs a deleted layer, the app downloads it again, and that is a charge to your AWS account.

To delete copies, select them in Versions by dataset, then push Delete selected. Read the list in the dialog, then push Delete.

Map visualizations shows the disk space that the stored map data uses. Type a value in Limit (GB), then push Save limit. The app keeps maps until you clear them. To clear map data, use Clear for selected Lists… or Hard clear all map data….

Memory¶

The Memory section sets how much memory the app can use. It has 4 parts:

1. Environment: Host / VM memory limit (GB). The app finds this value when it operates in a container. To set a lower value, push Override. To go back, push Use detected.
2. This app: Reserved for the operating system (GB) and Memory allocated to the application (GB). The default reserve is the larger of 3 GB and 10% of the host limit. The app also shows a recommended minimum. Until the app measures a value, the minimum is 2.0 GB.
3. How the allocation is split: a table of the shares. You cannot change the shares on this page. They are set in config.yaml (analysis.memory_shares) and apply after a restart.
4. Render detail: Max cells at native. This is the maximum number of cells that one view at native resolution can return.

To change the memory values:

Type the new values.
Make sure that the section shows no error.
Push Apply.

The values apply immediately. You do not have to restart the app.

CAUTION: If Memory allocated to the application (GB) is less than the recommended minimum, an analysis can fail. The app shows a warning, but it lets you apply the value.

Language¶

The language selector is in the top bar, to the right of ⚙ Settings. It has these languages: English (en), Español (es), Français (fr), Bahasa Indonesia (id) and Português (pt).

Push the language selector.
Select a language.

The app changes the language immediately. The browser keeps your selection for the next visit.

NOTE: This user guide is also available in the other languages of the app: Español, Français, Bahasa Indonesia and Português. Use the guide in the language that you select, so that the labels in the guide are the same as the labels on your screen.

The configuration file¶

The configuration file contains the settings that the Settings page cannot change. In the Docker image, the file is /data/config.yaml. The environment variable LUC_ANALYTICS_CONFIG can give a different path.

When the container starts for the first time, it makes /data/config.yaml from config.example.yaml. It turns on uploads and sets the download root to /data/datasets. The file also turns on the Copernicus provider. Refer to The Sentinel-2 basemap. The container never changes a configuration file that exists.

config.example.yaml lists each key with its default value. In the Docker image, /data/config.yaml is a full copy of that file, and the app reads only /data/config.yaml. If you remove a key from it, the app uses the default value in the program code. This value can be different from the value in config.example.yaml. For example, the program default of maps.cdse_enabled is false.

NOTE: If you start the app without Docker, with a file that has the name config.yaml, the app reads config.example.yaml first. The values in config.yaml then replace the values in config.example.yaml. We recommend that this config.yaml contains only the keys that you change.

These keys have a relation to the Settings page:

Key	What it controls
`datasets.download_roots`	The folders that downloads can go into. An empty list stops all downloads.
`datasets.browse_roots`	More folders that the folder browser shows. The app only reads these folders.
`datasets.upstream.region`, `datasets.upstream.regions`	The AWS region of the S3 sources. The WRI bucket is in `us-east-1`.
`datasets.upstream.cadence`	How frequently each dataset changes. This sets the Recommended choice.
`datasets.cost_model`	The prices that the app uses to calculate the cost of S3 reads.
`datasets.zarr_store.max_gb`	The limit for the automatic cache (live; default 50).
`viz.grid_store_max_gb`	The limit for map visualizations (live; default 2.0).
`analysis.memory_budget_gb`	The memory allocated to the app (live; default 1.5).
`analysis.memory_shares`	The shares of the memory allocation.
`analysis.zoom_adaptive.max_cells_ceiling`	Max cells at native (live; default 200000).
`security.*`	The master key, the secret store folder, the Docker secrets folder and the Credential Manager names.
`maps.*`	The basemap providers, for example `maps.cdse_enabled`.
`ingest.upload_enabled`	Uploads on or off.

A key with the word "live" in the table can also change on the Settings page. The page saves the value in the runtime overlay file (runtime.overlay_path, default ./data/runtime-overlay.yaml). In the Docker image, this file is /data/data/runtime-overlay.yaml. A value in the runtime overlay has priority over the same key in config.yaml. All other keys apply only after a restart.

Change the configuration file in Docker¶

The /data/config.yaml file is in the Docker volume, not on your computer. To change it, copy it out of the container, change the copy, and copy it back in. These steps use the container name luc-analytics from Install and start.

WARNING: Do not write credentials in config.yaml. The app does not read credentials from the configuration file. Use the Credentials section, environment variables, Docker secrets or the Windows Credential Manager.

CAUTION: Do not change the runtime overlay file by hand. If it contains a key that is not permitted, the app ignores the full file.

Open a terminal in a folder on your computer.
Copy the file out of the container:

docker cp luc-analytics:/data/config.yaml config.yaml

Make a second copy of config.yaml with the name config.yaml.bak. Keep it to put back if the change fails.
Open config.yaml in a text editor.
Find the key in config.example.yaml and copy its name exactly. To read config.example.yaml, type docker exec luc-analytics cat /app/config.example.yaml.
Change the value. Keep the indent of the YAML structure.
Save the file.
Copy the file back into the container:

docker cp config.yaml luc-analytics:/data/config.yaml

Restart the container:

docker restart luc-analytics

Type docker logs luc-analytics and read the log. If a key name is wrong, the log shows a warning with the full key name.

NOTE: docker cp makes the root user the owner of the copied file. The app operates as user 10001, and it only reads /data/config.yaml. Thus, you do not have to change the owner of the file.

CAUTION: An unknown key under security stops the configuration load. If the app does not start after a change, copy config.yaml.bak back into the container with docker cp, then restart the container.