> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tangoanalytics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy an on-premise gateway

# Prerequisites

For details about the requirements for the deployment of a Locatee gateway on-premise, please see the Gateway requirements section [here](https://docs.locatee.ch/docs/system-requirements)

## 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 -`

1. Create the Locatee service user and base directory:
   ```shell theme={null}
   useradd -m -s /bin/bash -U locatee
   mkdir -p /opt/locatee/gateway
   ```

2. Uninstall old Docker versions:

   > Note\
   > For Ubuntu follow the official documentation instead of using the commands below\
   > [https://docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/)

   ```shell theme={null}
   sudo yum -y remove docker \
   									 docker-client \
                      docker-client-latest \
                      docker-common \
                      docker-latest \
                      docker-latest-logrotate \
                      docker-logrotate \
                      docker-engine
   ```

3. Add the Docker repository:
   ```shell theme={null}
   sudo yum -y install yum-utils
   sudo yum-config-manager \
   --add-repo \
   https://download.docker.com/linux/centos/docker-ce.repo
   ```

4. Install and enable Docker:

   ```shell theme={null}
   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
   ```

5. **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](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy)

6. Install and enable Docker Compose:

   ```shell theme={null}
   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:
>
> ```shell theme={null}
> ## 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

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

```text theme={null}
/opt/locatee/gateway/keyfile.json
/opt/locatee/gateway/logging.json
```

2. Authenticate with the provided account to pull the gateway images:

```shell theme={null}
docker login -u _json_key -p "$(cat /opt/locatee/gateway/keyfile.json)" https://artifact.ch.locatee.com
```

## AWS

1. Install the AWS CLI on the machine, using the provider's [instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
2. Add the following block to `~/.aws/config`:

```
[profile locatee_on_prem]
```

3. 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.

4. Execute the following to generate `kubeconfig`:

```shell theme={null}
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

1. Open Locatee Analytics
2. Go to **Admin > Data Sources > Gateways**
3. Create a new **On-Prem** type gateway

4) Copy the generated token and note the gateway's unique ID:

![](https://files.readme.io/30c7521-Locatee_Admin.png)

## 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`

```yaml Google Cloud theme={null}
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
```

```yaml AWS theme={null}
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:

```shell theme={null}
/opt/locatee/gateway/gateway.yaml
```

# Startup

Start the gateway containers:

```shell theme={null}
docker-compose -f /opt/locatee/gateway/gateway.yaml up -d
```

Check all containers are up and running:

```shell theme={null}
docker-compose ps
```

Monitor the gateway container logs for any errors:

```shell theme={null}
docker logs gateway-prod -f
```

# Shutdown

Stop the gateway containers:

```shell theme={null}
docker-compose -f /opt/locatee/gateway/gateway.yaml down
```