Prerequisites

For details about the requirements for the deployment of a Locatee gateway on-premise, please see the Gateway requirements section here

Access credentials

Locatee will provide you with the following files:

Google Cloud

gateway JSON key for downloading the gateway Docker image from our repository.
logging JSON key for forwarding gateway logs to our monitoring service.

AWS

access key ID and secret access key for downloading the gateway Docker image from our repository.

Install Docker

📘 Note Full root permissions are required for the steps below.
Use sudo su -

Create the Locatee service user and base directory:

useradd -m -s /bin/bash -U locatee
mkdir -p /opt/locatee/gateway

Uninstall old Docker versions:

Note
For Ubuntu follow the official documentation instead of using the commands below
https://docs.docker.com/engine/install/ubuntu/

sudo yum -y remove docker \
									 docker-client \
                   docker-client-latest \
                   docker-common \
                   docker-latest \
                   docker-latest-logrotate \
                   docker-logrotate \
                   docker-engine

Add the Docker repository:

sudo yum -y install yum-utils
sudo yum-config-manager \
--add-repo \
https://download.docker.com/linux/centos/docker-ce.repo

Install and enable Docker:

sudo yum -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable docker --now
sudo usermod -aG docker locatee

# switch to Locatee user
su - locatee

# check Docker is running properly and on the latest version
docker version

Optional: If a proxy is set up on the server, make sure the proxy is also configured for Docker. See: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy

Install and enable Docker Compose:

sudo curl -SL https://github.com/docker/compose/releases/download/v2.14.2/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
sudo chmod 555 /usr/local/bin/docker-compose
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

📘 Optional: Importing certificates for REST API data sources If using REST API-based data sources such as Cisco ISE or Cisco CMX, follow the steps below to import their certificates into the Java trust store:

## Extract the root trust store
docker run --entrypoint /busybox/cp --rm -v /tmp/cacerts:/tmp/cacerts artifact.ch.locatee.com/molten-unison-255209/locatee-on-prem-repo/distroless/java:17-debug -v /usr/lib/jvm/java-17-openjdk-amd64/lib/security/cacerts /tmp/cacerts

## fetch the server certificates, and store the root certificate of the server chain in /tmp/cacerts/certificate_to_add.pem:
echo | openssl s_client -verify 5 -connect <GCLOUD-IP-ADDRESS>:443 -showcerts 2>/dev/null | openssl x509 -outform pem | sudo tee /tmp/cacerts/certificate.pem

## add the new certificate to the truststore
docker run --rm -it -v /tmp/cacerts:/tmp/cacerts artifact.ch.locatee.com/molten-unison-255209/locatee-on-prem-repo/openjdk:17-slim keytool -importcert -file /tmp/cacerts/certificate.pem -keypass changeit -storepass changeit -noprompt -alias mycustCert -keystore /tmp/cacerts/cacerts

## persist the store in a safe location
mv /tmp/cacerts/cacerts /opt/locatee/cacerts

Authenticate into the container registry

Google Cloud

Copy the provided gateway and logging JSON keys into the base directory under the following paths:

/opt/locatee/gateway/keyfile.json
/opt/locatee/gateway/logging.json

Authenticate with the provided account to pull the gateway images:

docker login -u _json_key -p "$(cat /opt/locatee/gateway/keyfile.json)" https://artifact.ch.locatee.com

AWS

Install the AWS CLI on the machine, using the provider’s instructions.
Add the following block to ~/.aws/config:

[profile locatee_on_prem]

Add the following block to ~/.aws/credentials:

[locatee_on_prem]  
aws_access_key_id =  
aws_secret_access_key =

Fill in the provided access key ID and secret access keys.

Execute the following to generate kubeconfig:

aws ecr get-login-password --region us-east-1 --profile locatee_on_prem | docker login --username AWS --password-stdin 425921203572.dkr.ecr.us-east-1.amazonaws.com

This will authenticate Docker with temporary token from AWS, allowing container images to be pulled from AWS ECR.

Configure the gateway

Create a gateway API token

Open Locatee Analytics
Go to Admin > Data Sources > Gateways
Create a new On-Prem type gateway

Copy the generated token and note the gateway’s unique ID:

Create a gateway configuration file

Locatee Gateways are deployed using standard Docker Compose YAML templates. Fill in the template below with the required values:

LOCATEE_GATEWAY_ID: ID of the gateway created earlier
LOCATEE_API_TOKEN: token of the gateway generated earlier
LOCATEE_API_URL: URL of the Locatee environment, for example <https://prod.customer.ch.locatee.com>
LOCATEE_CUSTOMER_NAME: short form name of the Locatee environment, for example customer-prod

Google Cloud

services:
  gateway-prod:
    image: artifact.ch.locatee.com/molten-unison-255209/locatee-on-prem-repo/gateway:stable
    container_name: gateway-prod
    restart: always
    environment:
      LOCATEE_GATEWAY_ID:
      LOCATEE_API_TOKEN:
      LOCATEE_API_URL: 
      LOCATEE_CUSTOMER_NAME:
      FEATURE_GATE_ANONYMIZATION_ENABLED: 'false'
      GOOGLE_APPLICATION_CREDENTIALS: /opt/locatee/logging.json
      # optional: if HTTP proxy is in use, remove comment from line below and replace with proxy details
      # JAVA_TOOL_OPTIONS: "-Dhttp.proxyHost=${HTTP_PROXY_IP} -Dhttp.proxyPort=${HTTP_PROXY_PORT} -Dhttps.proxyHost=${HTTPs_PROXY_IP} -Dhttps.proxyPort=HTTP_PROXY_PORT"
    volumes:
    # optional: if you imported custom certificates, remove comment from line below
    #  - /opt/locatee/cacerts:/usr/lib/jvm/java-17-openjdk-amd64/lib/security/cacerts:ro
      - /opt/locatee/gateway/logging.json:/opt/locatee/logging.json
    logging:
      driver: json-file
      options:
        max-size: 10M
  gateway-uat:
    image: artifact.ch.locatee.com/molten-unison-255209/locatee-on-prem-repo/gateway:stable
    container_name: gateway-uat
    restart: always
    environment:
      LOCATEE_GATEWAY_ID:
      LOCATEE_API_TOKEN:
      LOCATEE_API_URL: 
      LOCATEE_CUSTOMER_NAME:
      FEATURE_GATE_ANONYMIZATION_ENABLED: 'false'
      GOOGLE_APPLICATION_CREDENTIALS: /opt/locatee/logging.json
      # optional: if HTTP proxy is in use, remove comment from line below and replace with proxy details
      # JAVA_TOOL_OPTIONS: "-Dhttp.proxyHost=${HTTP_PROXY_IP} -Dhttp.proxyPort=${HTTP_PROXY_PORT} -Dhttps.proxyHost=${HTTPs_PROXY_IP} -Dhttps.proxyPort=HTTP_PROXY_PORT"
    volumes:
    # optional: if you imported custom certificates, remove comment from line below
    #  - /opt/locatee/cacerts:/usr/lib/jvm/java-17-openjdk-amd64/lib/security/cacerts:ro
      - /opt/locatee/gateway/logging.json:/opt/locatee/logging.json
    logging:
      driver: json-file
      options:
        max-size: 10M
  watchtower:
    image: artifact.ch.locatee.com/molten-unison-255209/locatee-on-prem-repo/watchtower
    container_name: watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/timezone:/etc/timezone:ro
      - /home/locatee/.docker/config.json:/config.json 
    command: gateway-prod gateway-uat
    environment:
      WATCHTOWER_CLEANUP: true
      WATCHTOWER_INCLUDE_RESTARTING: true
      WATCHTOWER_POLL_INTERVAL: 1800
  autoheal:
    image: artifact.ch.locatee.com/molten-unison-255209/locatee-on-prem-repo/autoheal
    container_name: autoheal
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      AUTOHEAL_CONTAINER_LABEL: all

AWS

services:
  gateway-prod:
    image: 425921203572.dkr.ecr.us-east-1.amazonaws.com/on-prem-snmp-gateway:stable
    container_name: gateway-prod
    restart: always
    environment:
      LOCATEE_GATEWAY_ID:
      LOCATEE_API_TOKEN:
      LOCATEE_API_URL: 
      LOCATEE_CUSTOMER_NAME:
      FEATURE_GATE_ANONYMIZATION_ENABLED: 'false'
      # optional: if HTTP proxy is in use, remove comment from line below and replace with proxy details
      # JAVA_TOOL_OPTIONS: "-Dhttp.proxyHost=${HTTP_PROXY_IP} -Dhttp.proxyPort=${HTTP_PROXY_PORT} -Dhttps.proxyHost=${HTTPs_PROXY_IP} -Dhttps.proxyPort=HTTP_PROXY_PORT"
    logging:
      driver: json-file
      options:
        max-size: 10M
  gateway-uat:
    image: 425921203572.dkr.ecr.us-east-1.amazonaws.com/on-prem-snmp-gateway:stable
    container_name: gateway-uat
    restart: always
    environment:
      LOCATEE_GATEWAY_ID:
      LOCATEE_API_TOKEN:
      LOCATEE_API_URL: 
      LOCATEE_CUSTOMER_NAME:
      FEATURE_GATE_ANONYMIZATION_ENABLED: 'false'
      # optional: if HTTP proxy is in use, remove comment from line below and replace with proxy details
      # JAVA_TOOL_OPTIONS: "-Dhttp.proxyHost=${HTTP_PROXY_IP} -Dhttp.proxyPort=${HTTP_PROXY_PORT} -Dhttps.proxyHost=${HTTPs_PROXY_IP} -Dhttps.proxyPort=HTTP_PROXY_PORT"
    logging:
      driver: json-file
      options:
        max-size: 10M
  watchtower:
    image: 425921203572.dkr.ecr.us-east-1.amazonaws.com/on-prem-snmp-gateway:watchtower
    container_name: watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/timezone:/etc/timezone:ro
      - /home/locatee/.docker/config.json:/config.json 
    command: gateway-prod gateway-uat
    environment:
      WATCHTOWER_CLEANUP: true
      WATCHTOWER_INCLUDE_RESTARTING: true
      WATCHTOWER_POLL_INTERVAL: 1800
  autoheal:
    image: 425921203572.dkr.ecr.us-east-1.amazonaws.com/on-prem-snmp-gateway:autoheal
    container_name: autoheal
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      AUTOHEAL_CONTAINER_LABEL: all

Store the filled template under the following path:

/opt/locatee/gateway/gateway.yaml

Startup

Start the gateway containers:

docker-compose -f /opt/locatee/gateway/gateway.yaml up -d

Check all containers are up and running:

docker-compose ps

Monitor the gateway container logs for any errors:

docker logs gateway-prod -f

Shutdown

Stop the gateway containers:

docker-compose -f /opt/locatee/gateway/gateway.yaml down

Get Started

Using Locatee Analytics

Create and Manage Buildings

Connect Your Data Sources

Calibrate Your Data Sources

Configure Access

Deploy an on-premise gateway

Prerequisites

Access credentials

Google Cloud

AWS

Install Docker

Authenticate into the container registry

Google Cloud

AWS

Configure the gateway

Create a gateway API token

Create a gateway configuration file

Startup

Shutdown

​Prerequisites

​Access credentials

​Google Cloud

​AWS

​Install Docker

​Authenticate into the container registry

​Google Cloud

​AWS

​Configure the gateway

​Create a gateway API token

​Create a gateway configuration file

​Startup

​Shutdown

Prerequisites

Access credentials

Google Cloud

AWS

Install Docker

Authenticate into the container registry

Google Cloud

AWS

Configure the gateway

Create a gateway API token

Create a gateway configuration file

Startup

Shutdown