Skip to main content

​
Prerequisites

Before installing, ensure you have:
  • Kubernetes v1.23 or higher
  • Helm v3.7.0 or higher
  • Helmfile v0.144.0 or higher (recommended)
  • Docker Hub account with access granted by Loqate
  • Loqate license key (API key)
  • Persistent storage - At least 250Gi ReadWriteMany (RWX) volume
Recommended tools: Istio v1.11.4+, KEDA v2.4+, Prometheus v2.34.0+ for advanced features

​
Step 1: Prepare Your Environment

Create a working directory and set environment variables. Unix/Linux: 
# Create directory
mkdir -p /opt/loqate/lqtcharts
cd /opt/loqate/lqtcharts

# Set credentials (required)
export LICENSE_KEY="your-api-key"
export DOCKER_USERNAME="your-docker-username"
export DOCKER_PASSWORD="your-docker-password"

# Set custom data path (optional)
export LOQATE_NFS_SHARE="/opt/loqate/data"

# Use existing PVC (optional)
export CLAIM_OVERRIDE="your-pvc-name"
Windows (PowerShell): 
# Create directory
New-Item -Path "\loqate\lqtcharts" -ItemType "Directory"
Set-Location "\loqate\lqtcharts"

# Set credentials (required)
$env:LICENSE_KEY="your-api-key"
$env:DOCKER_USERNAME="your-docker-username"
$env:DOCKER_PASSWORD="your-docker-password"

# Set custom data path (optional)
$env:LOQATE_NFS_SHARE="/run/desktop/mnt/host/c/loqate/data"

# Use existing PVC (optional)
$env:CLAIM_OVERRIDE="your-pvc-name"
Default behavior: Creates a Persistent Volume (PV) and Persistent Volume Claim (PVC) using host filesystem at the path specified by LOQATE_NFS_SHARE.Custom data path: Set LOQATE_NFS_SHARE to your desired storage location.Existing PVC: Set CLAIM_OVERRIDE to use a pre-configured PVC for network storage. Skip LOQATE_NFS_SHARE if using this option.

​
Step 2: Download Helmfile

Unix/Linux: 
wget https://charts.loqate.com/helmfile.yaml -O helmfile.yaml
Windows (PowerShell): 
Invoke-WebRequest https://charts.loqate.com/helmfile.yaml -OutFile helmfile.yaml

​
Step 3: Install Verify

Unix/Linux: 
helmfile apply
Windows (PowerShell): 
helmfile sync
The installation will:
  1. Create the loqate namespace
  2. Pull container images from Docker Hub
  3. Deploy Memberlist, QueryCoordinator, and Spatial-API
  4. Start InstallManager to download reference data
Data download takes several hours and requires at least 250Gi storage for the full dataset.

​
Step 4: Monitor Installation Progress

Check pod status: 
kubectl get pods -n loqate
Expected output during installation: 
NAME                           READY   STATUS    RESTARTS   AGE
installmanager-xxxxx           0/1     Running   0          2m
memberlist-xxxxx               1/1     Running   0          2m
querycoordinator-xxxxx         0/1     Running   0          2m
spatial-api-xxxxx              0/1     Running   0          2m
Monitor data download: 
kubectl logs -f installmanager-xxxxx -n loqate
Installation is complete when you see Edit complete in the logs.

​
Step 5: Test Your Installation

Open a port forward: 
kubectl port-forward -n loqate svc/querycoordinator 8900:8900
Test version endpoint (Unix/Linux): 
curl -X GET http://localhost:8900/api/version
Expected response: 
{"version":"2.xx.x.xxxxx-xxxxxxx"}
Test verification (Unix/Linux): 
curl -X POST http://localhost:8900/verify \
  -H "Content-Type: application/json" \
  -d '{"input":[{"Address1":"The Foundation","Locality":"Chester","Country":"GB"}]}'
Successful response includes validated address with AVC and AQI scores.
Test version:
Invoke-WebRequest -Method GET http://localhost:8900/api/version
Test verification:
Invoke-WebRequest http://localhost:8900/verify -Method POST `
  -ContentType "application/json" `
  -Body '{"input":[{"Address1":"The Foundation","Locality":"Chester","Country":"GB"}]}'

​
Download Subset of Datasets

To reduce storage and download time, install only specific countries:
  1. Create silent.txt file:
gbgkey=your-api-key
datachoice=selectcountries
countries=USA,GBR,CAN
  1. Create ConfigMap:
kubectl create configmap installmanager-config \
  --from-file=silent.txt=silent.txt \
  -n loqate
  1. Update InstallManager values to reference the ConfigMap
  2. Rerun helmfile

​
Troubleshooting Installation

Pods not starting: Check logs: 
kubectl logs pod-name -n loqate
Common issues: invalid license key, Docker Hub authentication failed, insufficient storage. Data download slow: Normal for full dataset. Monitor with: 
kubectl logs -f installmanager-xxxxx -n loqate
Connection refused on port forward: Ensure port forward is running and QueryCoordinator pod shows 1/1 ready status. See Troubleshooting for more solutions.

​
Next Steps