Stand with Ukraine flag
Try it now Pricing
PE Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Configuration Guides > Installing Edge Behind a Proxy
Getting Started
Devices Library Installation Architecture API FAQ
On this page

Installing Edge Behind a Proxy

Overview

Installing Edge behind a proxy means that the Edge instance cannot directly access the internet and all communication to ThingsBoard Cloud or any other external service is routed through a proxy server.

Compare:

  • Without Proxy (direct connection):

Without Proxy

  • With Proxy (indirect connection):

With Proxy

Using a proxy server allows enhancing security by filtering and monitoring internet traffic. In restricted environments, direct internet access is often deliberately blocked, making proxy configurations a necessity for maintaining security protocols.

Beyond security, proxies can cache resources that can substantially reduce overall network consumption and improve performance for distributed systems like ThingsBoard Edge.

The Installation Guide

Debian-based installation
Docker-based installation

Prerequisites

  • Have a proxy server (HTTP or HTTPS) with its address, port, and credentials (if required).
  • Consider the addresses that should bypass the proxy (e.g., internal resources).
  • Have Java 17 installed.
  • ThingsBoard Edge is installed and running.

Step 1. Modify Configuration File

To configure ThingsBoard Edge behind proxy running on debian-based installation (e.g., Ubuntu), modify the tb-edge.conf file:

1
2
3
4
5
6
7
8

sudo tee -a /etc/tb-edge/conf/tb-edge.conf > /dev/null <<EOL
#Enable the proxy
export CLOUD_RPC_PROXY_ENABLED=true

#Set the proxy server host and port
export CLOUD_RPC_PROXY_HOST="proxy_host"
export CLOUD_RPC_PROXY_PORT="proxy_port"
EOL
  • Replace proxy_host and proxy_port with your proxy’s hostname and port.
  • If there are hosts that should bypass the proxy (e.g., local network addresses), set using a format like: localhost|127.0.0.1|yourdomain.com
Configure Authentication (If Required)

If your proxy requires authentication, add the following parameters:

1
2
3

#(Optional) Add authentication if required
export CLOUD_RPC_PROXY_USERNAME="proxy_username"
export CLOUD_RPC_PROXY_PASSWORD="proxy_password"
  • Replace proxy_user and proxy_password with your actual credentials.
Verify the Changes (Optional)

To verify the changes, run the following command:

1

cat /etc/tb-edge/conf/tb-edge.conf

Step 2. Restart ThingsBoard Edge

For the changes to take effect, restart the service after modifying the tb-edge.conf file:

1

sudo service tb-edge restart

Once the Edge service is started, open the Edge UI at http://localhost:8080. Use the tenant credentials to log in.

Doc info icon

If the Edge HTTP bind port was changed to 18080 during Edge installation, access the ThingsBoard Edge instance at http://localhost:18080.

Troubleshooting

ThingsBoard Edge logs stored in the following directory:

1

/var/log/tb-edge

To check if there are any errors on the service side:

1

cat /var/log/tb-edge/tb-edge.log | grep ERROR

Check connectivity:

1

curl -x http://proxy_host:proxy_port https://your_tb_cloud_url
  • Replace proxy_host and proxy_port with your proxy’s hostname and port.

Confirm that the service can reach the proxy server:

1
2

ping proxy_host
traceroute proxy_host
  • Replace proxy_host with your proxy’s hostname.

Next Steps

Prerequisites

  • Have a proxy server (HTTP or HTTPS) with its address, port, and credentials (if required).
  • Have ThingsBoard Edge installed and running, and ThingsBoard Cloud accessible.
  • Have Docker and Docker Compose installed on your machine.
Doc info icon

To proceed with proxy configuration, set the terminal in the directory which contains the docker-compose.yml file.

Step 1. Stop Docker Container

Stop the currently running TB Edge container (if it’s still running):

1

docker compose stop

Step 2. Modify the .yml File

Update the docker-compose.yml file with the proxy settings.

To open the file, use:

1

sudo nano docker-compose.yml

Enter the following lines into the “environment” block within the file:

1
2
3

      HTTP_PROXY: http://proxy_user:proxy_password@<proxy_host:proxy_port
      HTTPS_PROXY: http://proxy_user:proxy_password@<proxy_host:proxy_port
      NO_PROXY: localhost,127.0.0.1,postgres,PUT_YOUR_CLOUD_IP
  • Specify the proxy server for HTTP and HTTPS connections in the HTTP_PROXY and HTTPS_PROXY lines, correspondingly
  • List addresses that should bypass the proxy in the NO_PROXY line
    • For example: NO_PROXY=localhost,127.0.0.1,postgres,demo.thingsboard.io

The expected result:

Step 3 Restart the Containers

To start this docker compose, run the following command:

1

docker compose up -d && docker compose logs -f mytbedge

Once the Edge service is started, open the Edge UI at http://localhost:8080. Use the tenant credentials to log in.

Doc info icon

If the Edge HTTP bind port was changed to 18080 during Edge installation, access the ThingsBoard Edge instance at http://localhost:18080.

Troubleshooting

Confirm that the proxy environment variables are correctly set in the docker-compose.yml file:

1
2
3

echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

If the variables are not set, check if they are correctly applied in the container:

1

docker exec -it container_name printenv | grep -i proxy

If missing, ensure that they are properly defined in docker-compose.yml.

Once the container is running, verify if it can access the internet via the proxy:

1

docker exec -it container_name curl -I https://google.com

If the request fails, it may indicate incorrect proxy settings or connectivity issues.

Check Docker container logs for any additional proxy-related errors:

1

docker logs container_name

Check connectivity:

1

curl -x http://proxy_host:proxy_port https://your_tb_cloud_url

Next Steps