Client setup - Spatial Data Management on AWS
PrerequisitesWeb portal setupDesktop Client setupCLI setupSystem requirements and browser compatibilityTroubleshootingGetting help

Client setup

This section describes how to set up and configure the three client applications for accessing Spatial Data Management on AWS:

  • Web portal – Browser-based interface for resource management (libraries, projects, assets metadata)

  • Command-Line Interface (CLI) – Python-based CLI tool for automation and scripting

  • Desktop application – Native application for Windows, macOS, and Linux with full asset upload and download capabilities (requires CLI to be installed first)

Prerequisites

Before setting up any client application, ensure you have:

  • Deployed the Spatial Data Management on AWS solution in your AWS account

  • Amazon Cognito user credentials (username and password) from your IT Administrator

  • API endpoint URL from your deployment

  • Network access to your deployment (VPN if required)

Client application capabilities

Web portal:

  • Use for resource management (creating libraries, projects, managing metadata, searching assets)

  • No file upload or download capabilities

CLI or desktop application:

  • Required for uploading and downloading asset files

  • Full resource management capabilities

  • The desktop application requires the CLI to be installed first

Web portal setup

The web portal requires no installation and can be accessed directly through a web browser.

Access the web portal

  1. Request the portal URL from your IT Administrator or the person who deployed the {solution-name} solution in your organization.

  2. (Optional) If you have AWS CLI access, you can retrieve the portal URL from AWS CloudFormation outputs:

    # Replace <stack-name> with your CloudFormation stack name
aws cloudformation describe-stacks \
  --stack-name <stack-name> \
  --query 'Stacks[0].Outputs[?OutputKey==`PortalUrl`].OutputValue' \
  --output text

  3. Open the URL in a supported web browser:

    • Google Chrome

    • Mozilla Firefox

    • Microsoft Edge

    • Safari

  4. Sign in with your Amazon Cognito credentials provided by your IT Administrator.

Desktop Client setup

Important: The desktop application requires the CLI to be installed. If you plan to use the desktop application, install the CLI after completing this section.

Download desktop application

Download the appropriate installer for your platform from the links provided by your IT Administrator:

Installation instructions

Windows installation

  1. Double-click the downloaded .exe file.

  2. If Windows SmartScreen appears, choose More info, and then choose Run anyway.

  3. Follow the installation wizard:

    • Accept the license agreement

    • Choose installation location (default: C:\Program Files\SpatialDataManagement)

    • Choose whether to create desktop shortcut

    • Choose Install

  4. Launch the application from Start Menu or desktop shortcut.

macOS installation

Choose the correct version for your Mac:

  • Apple Silicon Macs (M1, M2, M3): Download the aarch64.dmg version for best performance

  • Intel Macs: Download the x64.dmg version

  • Not sure? Go to Apple Menu, choose About This Mac, and check the "Chip" field

    1. Double-click the downloaded .dmg file.

    2. Drag the Spatial Data Management icon to the Applications folder.

    3. Open Applications folder and double-click Spatial Data Management.

    4. The application launches.

Security note: The application is digitally signed. If macOS shows a security warning about an unidentified developer, do not proceed with the installation. Contact your IT Administrator to verify you have the official signed application.

Linux installation

Option 1: AppImage (Recommended for most users)

  1. Make executable and run:

    chmod +x spatial-data-portal_0.1.0_amd64.AppImage
./spatial-data-portal_0.1.0_amd64.AppImage

  2. (Optional) Integrate with system:

    # Move to applications directory
sudo mkdir -p /opt/spatial-data-management
sudo mv spatial-data-portal_0.1.0_amd64.AppImage /opt/spatial-data-management/

# Create desktop entry
cat > ~/.local/share/applications/spatial-data-management.desktop <<EOF
[Desktop Entry]
Name=Spatial Data Management
Exec=/opt/spatial-data-management/spatial-data-portal_0.1.0_amd64.AppImage
Icon=spatial-data-management
Type=Application
Categories=Utility;
EOF

Option 2: DEB Package (Ubuntu/Debian) 

sudo dpkg -i spatial-data-portal_0.1.0_amd64.deb
sudo apt-get install -f  # Fix any dependency issues if needed

Option 3: RPM Package (Red Hat/Fedora/SUSE) 

# Red Hat/CentOS
sudo rpm -i spatial-data-portal-0.1.0-1.x86_64.rpm

# Fedora (preferred method)
sudo dnf install spatial-data-portal-0.1.0-1.x86_64.rpm

# SUSE
sudo zypper install spatial-data-portal-0.1.0-1.x86_64.rpm

Configure desktop application

  1. Launch the application.

  2. Sign in with your Amazon Cognito credentials provided by your IT Administrator.

CLI setup

The desktop application provides enhanced performance for large file operations and offline capabilities.

Prerequisite: The CLI must be installed before you install the desktop application. If you have not installed the CLI yet, see CLI setup.

Prerequisites

  • Python 3.8 or later

  • pip (Python package installer)

Verify Python installation

# Check Python version
python --version
# or
python3 --version

# Check pip version
pip --version
# or
pip3 --version

If Python is not installed, download from python.org.

Install CLI from wheel file

Step 1: Obtain CLI wheel file

Download the CLI wheel file (.whl) from your IT Administrator or from the Amazon S3 location:

Download CLI wheel Download Checksum 

# Download from S3 (requires AWS CLI and appropriate permissions)
# Replace amzn_spatial_data_mgmt-0.1.0-py3-none-any.whl with the specific version provided by your IT Administrator.
aws s3 cp s3://solutions-reference/spatial-data-management/latest/artifacts/cli/amzn_spatial_data_mgmt-0.1.0-py3-none-any.whl .

# Download SHA256 checksum file
aws s3 cp s3://solutions-reference/spatial-data-management/latest/artifacts/cli/amzn_spatial_data_mgmt-0.1.0-py3-none-any.whl.sha256 .

Step 2: Verify file integrity (recommended)

Verify the downloaded file using the SHA256 checksum:

Windows (PowerShell): 

# Calculate SHA256 hash (replace <filename> with your downloaded file)
$hash = Get-FileHash -Algorithm SHA256 <filename>.whl

# Compare with expected hash
$expectedHash = Get-Content <filename>.whl.sha256

if ($hash.Hash -eq $expectedHash.Split()[0]) {
    Write-Host "Checksum verified successfully" -ForegroundColor Green
} else {
    Write-Host "Checksum verification failed" -ForegroundColor Red
}

macOS and Linux: 

# Verify checksum (replace <filename> with your downloaded file)
sha256sum -c <filename>.whl.sha256

# Expected output: <filename>.whl: OK

Important: Do not proceed with installation if the checksum verification fails. Contact your IT Administrator for a valid file.

Step 3: Install CLI wheel file

Windows: 

# Install CLI (replace <filename> with your downloaded file)
pip install <filename>.whl

# Verify installation
spatial-data-mgmt -h

macOS and Linux: 

# Install CLI (replace <filename> with your downloaded file)
pip3 install <filename>.whl

# Or install for current user only (if you do not have admin rights)
pip3 install --user <filename>.whl

# Verify installation
spatial-data-mgmt -h

CLI usage examples

# List projects
spatial-data-mgmt project list

# Add a member as a viewer to a project
spatial-data-mgmt project member add --project-id <project-id> --principal-id <principal-id> --principal-type USER --membership-level VIEWER

Update CLI

To update to a newer version:

# Uninstall current version
pip uninstall amzn-spatial-data-mgmt

# Install new version (replace <filename> with your downloaded file)
pip install <filename>.whl

# Verify new version
spatial-data-mgmt -h

Uninstall CLI

# Uninstall CLI
pip uninstall amzn-spatial-data-mgmt

# Remove configuration (optional)
rm -rf ~/.sdma

System requirements and browser compatibility

Web portal browser requirements

Supported browsers:

  • Google Chrome 90 or later (recommended)

  • Mozilla Firefox 88 or later

  • Microsoft Edge 90 or later

  • Safari 14 or later

Browser settings:

  • JavaScript must be enabled

  • Cookies must be enabled for authentication

  • Local storage required for session management

Desktop application system requirements

Windows:

  • Windows 10 or later (64-bit)

  • 4 GB RAM minimum (8 GB recommended)

  • 500 MB available disk space

macOS:

  • macOS 11 (Big Sur) or later

  • Apple Silicon or Intel processor

  • 4 GB RAM minimum (8 GB recommended)

  • 500 MB available disk space

Linux:

  • Ubuntu 20.04 LTS or later

  • Debian 11 or later

  • Fedora 35 or later

  • 4 GB RAM minimum (8 GB recommended)

  • 500 MB available disk space

CLI system requirements

  • Python 3.8 or later

  • pip (Python package installer)

  • 100 MB available disk space

Troubleshooting

This section provides solutions to common issues you might encounter when setting up or using the client applications.

Web portal issues

Issue: Cannot access portal URL

  • Verify the URL is correct from your IT Administrator

  • If you have AWS CLI access, retrieve the portal URL from AWS CloudFormation:

    aws cloudformation describe-stacks --stack-name $(aws cloudformation list-stack-resources --stack-name <YOUR STACK> --query 'StackResourceSummaries[?starts_with(LogicalResourceId, `PortalStackNested`)].PhysicalResourceId' --output text) --query 'Stacks[0].Outputs[?OutputKey==`PortalCloudFrontDistributionUrl`].OutputValue' --output text

  • Check network connectivity and VPN if required

  • Verify Amazon CloudFront distribution is deployed

  • Try accessing from a different browser

Issue: Login fails

  • Verify Amazon Cognito credentials are correct

  • Check if user account is enabled in Amazon Cognito User Pool

  • Verify user is assigned to appropriate group

  • Clear browser cache and cookies

  • Try incognito/private browsing mode

Issue: Portal loads but features do not work

  • Verify JavaScript is enabled in browser

  • Check browser console for errors (F12)

  • Ensure cookies and local storage are enabled

  • Update browser to latest version

Desktop application issues

Issue: Application will not start

  • Verify system requirements are met

  • Check antivirus is not blocking the application

  • Verify CLI is installed (required dependency)

  • Review application logs in:

    • Windows: %APPDATA%\SpatialDataManagement\logs

    • macOS: ~/Library/Application Support/SpatialDataManagement/logs

    • Linux: ~/.config/SpatialDataManagement/logs

Issue: Desktop application cannot find CLI

  • Verify CLI is installed: Test from command line with spatial-data-mgmt --version

  • On macOS/Linux, ensure CLI is in PATH: which spatial-data-mgmt

  • On Windows, ensure CLI is in PATH: where spatial-data-mgmt

  • Reinstall CLI if necessary

Issue: Cannot connect to API

  • Verify API endpoint URL is correct

  • Check network connectivity

  • Verify VPN connection if required

  • Check firewall settings

  • Verify CLI is properly configured

Issue: File uploads fail

  • Check available disk space

  • Verify network stability

  • Check file permissions

  • Review upload logs for specific errors

  • Try smaller files first to isolate issue

Issue: File downloads fail

  • Check available disk space in download location

  • Verify network stability

  • Check write permissions for download directory

  • Review download logs for specific errors

CLI issues

Issue: Command not found after installation

  • Verify installation: pip list | grep spatial

  • Check PATH includes Python scripts directory

  • On macOS/Linux with --user install, add ~/.local/bin to PATH

  • Reinstall CLI if necessary

Issue: Authentication fails

  • Verify API endpoint URL is correct in config file

  • Check Amazon Cognito credentials

  • Verify network connectivity

  • Check if user account is enabled

  • Verify config file format is correct YAML

Issue: SSL certificate errors

  • Update CA certificates: pip install --upgrade certifi

  • Verify system time is correct

  • Check corporate proxy settings

  • Verify API endpoint URL uses HTTPS

Issue: Slow upload/download performance

  • Adjust chunk size in config file

  • Increase concurrent transfers (max_concurrent_transfers)

  • Check network bandwidth

  • Verify no VPN bottlenecks

  • Test network speed to AWS Region

Issue: Python version conflicts

  • Verify Python 3.8 or later is installed

  • Check pip is using correct Python version: pip --version

  • Ensure you are using pip3 on macOS/Linux if multiple Python versions exist

Getting help

Web portal

  • In-app help: Choose the ? icon in top navigation

  • User guide: Available in portal under Help, and then choose Documentation

Desktop application

  • In-app help: Help → Documentation

  • Logs location:

    • Windows: %APPDATA%\SpatialDataManagement\logs

    • macOS: ~/Library/Application Support/SpatialDataManagement/logs

    • Linux: ~/.config/SpatialDataManagement/logs

CLI

  • Command help: spatial-data-mgmt --help

  • Subcommand help: spatial-data-mgmt <command> --help