--- title: "Deploy an on-premise connector host" slug: "deploy-an-on-premise-connector-host" status: "update" updated: 2026-08-13T06:26:41Z published: 2026-08-13T06:26:41Z canonical: "support.tulip.co/deploy-an-on-premise-connector-host" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.tulip.co/llms.txt > Use this file to discover all available pages before exploring further. # Deploy an on-premise connector host *Learn the technical steps for deploying, configuring, and maintaining On-Premise Connector Hosts (OPCH) for your Tulip integrations.* This article is a technical reference guide for individuals responsible for the physical deployment and lifecycle management of the OPCH. The Connector Host is a service used to facilitate connections from to external web services, databases, and OPC UA servers. All Tulip instances have a Cloud Connector Host by default. There are several considerations to make when determining if an On-Premise Connector Host is the correct architecture fit. ## Prerequisites Before you continue, ensure you've learned the basics of Tulip Connector Hosts: - [Connector hosts](https://support.tulip.co/docs/introduction-to-tulip-connector-hosts) - [On-premise connector hosts](/r230/docs/overview-of-on-premise-connector-hosts) ## Networking The most common rationale for deploying an On-Premise Connector Host is for the advantages it offers when connecting to systems hosted within a local network. With the on-premise offering, all connections from Tulip to external systems start from within your local network. All connections from your network are outbound to Tulip via a secure WebSocket. This contrasts with Cloud Connector Hosts, which require inbound access to the services. This is typically an IT decision to allow inbound secure WebSocket connections from [Tulip's cloud](https://support.tulip.co/docs/networking-requirements-for-a-tulip-cloud-deployment) to the service, often times using port forwarding rules on the WAN router/firewall. ## Deploy an On-Premise Connector Host Update to Support and Troubleshooting Starting with LTS16+, OPCH includes two environment variables to help with troubleshooting and support: TULIP_LOGGING_TO_TULIP (logging) and TULIP_TELEMETRY_TO_TULIP (metric reporting). To explicitly opt out, you can comment out the above environment variables. ### Technical standards OPCH performance The amount of resources needed to run OPCH will increase as its usage increases. If you consistently use it beyond 250Hz of throughput, we strongly advise allocating more resources to your virtual machines to ensure optimal performance. When the decision is made to deploy an on-premise solution, Tulip recommends a self-service route using a distributed [Docker](https://www.docker.com/resources/what-container) image. The easiest way to to accomplish this would be to use a virtual machine with a distribution of Linux. Tulip also recommends to host only one On-Premise Connector Host per virtual machine to avoid a single point of failure for sites. Virtual machine requirements: - RAM - 4 GB - ROM - 8-16GB disk size - CPU - 2 core - Docker version - 20.10+ For networking requirements, the On-Premise Connector Host has the following: - An IP address - DNS resolution to - Outbound access on port 443 to Tulip (IPs listed [here](https://support.tulip.co/docs/networking-requirements-for-a-tulip-cloud-deployment)) - Outbound access to the Docker repository [here](http://bckca2dh98.execute-api.us-east-1.amazonaws.com/) - Outbound access to all relevant external systems with ports Review the complete list of network requirements [here](https://support.tulip.co/docs/networking-requirements-for-a-tulip-cloud-deployment) ### Deployment The following section outlines how to deploy an On-Premise Connector Host in a variety of environments. AWS and Azure both offer container services capable of running the Docker image. #### AWS Use the Web UI and this instruction set: [https://aws.amazon.com/getting-started/hands-on/deploy-docker-containers/](https://aws.amazon.com/getting-started/hands-on/deploy-docker-containers/) #### Azure (Bash): LTS16+ OPCH ``` az container create ` -g ` --name ` --cpu 2 ` --memory 3 ` --restart-policy Always ` --image bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ` --os-type Linux ` -e TULIP_UUID='' ` TULIP_FACTORY='https://.tulip.co' ` TULIP_MACHINE_SECRET='' ` TULIP_DEVICE_TYPE='onprem' ` TULIP_LOGGING_TO_TULIP=true` TULIP_TELEMETRY_TO_TULIP=true` TULIP_CONNECTORS_HTTP_PROXY='' ` TULIP_CONNECTORS_HTTPS_PROXY='' ``` #### Azure (Bash): pre-LTS16 OPCH ``` az container create ` -g ` --name ` --cpu 2 ` --memory 3 ` --restart-policy Always ` --image bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ` --os-type Linux ` -e TULIP_UUID='' ` TULIP_FACTORY='https://.tulip.co' ` TULIP_MACHINE_SECRET='' ` TULIP_DEVICE_TYPE='onprem' ` CONNECTORS_HTTP_PROXY='' ` CONNECTORS_HTTPS_PROXY='' ``` #### Linux VM: LTS16+ OPCH ``` docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://.tulip.co' \ -e TULIP_UUID='' \ -e TULIP_MACHINE_SECRET='' \ -e TULIP_DEVICE_TYPE='onprem' \ -e TULIP_LOGGING_TO_TULIP=true \ -e TULIP_TELEMETRY_TO_TULIP=true \ -e TULIP_CONNECTORS_HTTP_PROXY='' \ -e TULIP_CONNECTORS_HTTPS_PROXY='' \ --restart=always \ --net=host \ bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ``` #### Linux VM: pre LTS16 OPCH ``` docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://.tulip.co' \ -e TULIP_UUID='' \ -e TULIP_MACHINE_SECRET='' \ -e TULIP_DEVICE_TYPE='onprem' \ -e CONNECTORS_HTTP_PROXY='' \ -e CONNECTORS_HTTPS_PROXY='' \ -e EXIT_ON_DISCONNECT=true \ --restart=always \ --net=host \ --mount type=volume,source=tuliplog,target=/log \ bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ``` #### Windows (PowerShell): LTS16+ OPCH ``` docker run -d --name tulip-connector-host -e TULIP_FACTORY='https://.tulip.co' -e TULIP_UUID='' -e TULIP_MACHINE_SECRET='' -e TULIP_DEVICE_TYPE='onprem' -e TULIP_LOGGING_TO_TULIP=true -e TULIP_TELEMETRY_TO_TULIP=true -e TULIP_CONNECTORS_HTTP_PROXY='' -e TULIP_CONNECTORS_HTTPS_PROXY='' --restart=always --net=host bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ``` #### Windows (PowerShell): pre-LTS16 OPCH ``` docker run -d --name tulip-connector-host -e TULIP_FACTORY='https://.tulip.co' -e TULIP_UUID='' -e TULIP_MACHINE_SECRET='' -e TULIP_DEVICE_TYPE='onprem' -e HTTP_PROXY='' -e HTTPS_PROXY='' -e EXIT_ON_DISCONNECT=true --restart=always --net=host --mount type=volume,source=tuliplog,target=/log bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ``` ### Troubleshoot certificate errors If OPCH fails to start with "self-signed certificate in certificate chain" errors, the root cause could be that corporate proxy/firewall with custom certificates prevents secure connections to Tulip Cloud. **Symptoms** - OPCH shows "Never seen" status - Process terminates during startup - SSL certificate chain errors in logs To solve this, use additional certificate authorities can be referenced during OPCH startup with the following environment variable as in below. To note, the file should be present on the docker container. **For pre-LTS16 OPCH:** ``` -e CONNECTORS_EXTRA_TRUSTED_CAS_FROM_FILES='["/etc/tulipCa/ca.pem"]' ``` **For LTS16+ OPCH:** ``` -e TULIP_CONNECTORS_EXTRA_TRUSTED_CAS_FROM_FILES='["/etc/tulipCa/ca.pem"]' ``` --- ## Upgrade an On-Premise Connector Host Version compatibility OPCH must be kept up-to-date with the Tulip product. Learn more about [OPCH version support](/r230/docs/on-prem-connector-host-version-support). Recommended upgrade procedure for OPCH Tulip recommends proactively confirming the upgrade by successfully running a test OPCH connection to the development environment and/or development instance. Once this verification is complete, the production environment can be confidently upgraded. Details on how can be found below. Your Edge IO may also need an upgrade OPCH can run on Edge IO devices. If your device doesn’t have auto-upgrade enabled, it must be upgraded manually. If this warning banner still appears after you've completed all OPCH upgrades, please make sure your Edge IO has also been updated. Tulip releases updates to the On-Premise Connector Host in accordance to our long term support (LTS) release schedule. To upgrade the service, following the below instructions: The upgrade process for an OPCH will result in downtime while the pod is stopped and recreated. 1. Obtain the latest version of the On-Premise Connector Host Docker image. ``` docker pull bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ``` 2. Run the below command to get the Docker container ID. ``` docker ps ``` 3. If you have access to the `TULIP_FACTORY`, `TULIP_UUID`, and `TULIP_MACHINE_SECRET`, go to step 4. If not, run the following command and store the output of this command in a secure location. ``` docker exec env ``` 4. Stop the existing Docker container. ``` docker stop ``` 5. Remove the existing Docker container. ``` docker rm ``` 6. Run the standard `Docker run` command leveraging the set of credentials stored. **For LTS16+ OPCH:** ``` docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://.tulip.co' \ -e TULIP_UUID='' \ -e TULIP_MACHINE_SECRET='' \ -e TULIP_DEVICE_TYPE='onprem' \ -e TULIP_LOGGING_TO_TULIP=true \ -e TULIP_TELEMETRY_TO_TULIP=true \ -e TULIP_CONNECTORS_HTTP_PROXY='' \ -e TULIP_CONNECTORS_HTTPS_PROXY='' \ --restart=always \ --net=host \ bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ``` **For pre-LTS16 OPCH:** ``` docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://.tulip.co' \ -e TULIP_UUID='' \ -e TULIP_MACHINE_SECRET='' \ -e TULIP_DEVICE_TYPE='onprem' \ -e CONNECTORS_HTTP_PROXY='' \ -e CONNECTORS_HTTPS_PROXY='' \ -e EXIT_ON_DISCONNECT=true \ --restart=always \ --net=host \ --mount type=volume,source=tuliplog,target=/log \ bckca2dh98.execute-api.us-east-1.amazonaws.com/public/connector-host: ``` 1. Confirm the new Docker container is active. ``` docker ps ``` ### Use connector environments to test your upgrade Each connector have three different environments (production, pre-production and development) and each of these environments can have their own connector host and they can be of different versions. Depending on the state of the application (development version, pending approval, published) a different environment can be used. The expected process to do connector host validation should be: 1. Upgrade your development OPCH 2. Upgrade your validation connector host (pre-production environment points at dev here) 1. Test your connector in the connectors page, or in development mode of your application 3. When validation testing is complete, upgrade the production connector host See [Connector environments](/r230/docs/how-to-run-a-connector-function-in-multiple-environments) for more information. Alternatively, you can upgrade your OPCH on your development instance, and then confidently upgrade the production environment. ## Log to external log management tools Availability This capability is available for LTS15+ OPCH. You can forward On-Premise Connector Host logs to third-party tools for centralized monitoring and troubleshooting. OPCH supports Datadog, Grafana Loki, and Splunk via environment variables. The types of logs available are related to your OPCH's health (especially around its connection to factory), connector call execution and subscription logs. As part of OPCH startup flow, users can provide configuration for external logging tool where they would like logs routed. If credentials for multiple services are added, logs are sent to all services 1. Pick your destination - **Datadog**: Global endpoint; only an API key is required. - **Grafana Loki**: Customer-hosted Loki; URL can include basic auth. - **Splunk (HEC)**: Multi-instance; requires both URL and token. 1. Add environment variables Add the variables below to the Connector Host environment. Use only the ones for your chosen destination. **Datadog** - `TULIP_LOGGING_DATADOG_API_KEY=<your_datadog_api_key>` **Grafana Loki** - `TULIP_LOGGING_LOKI_URL=https://<user>:<password>@loki.your-domain.com/loki/api/v1/push` *(Basic auth is supported by embedding `user:password` in the URL — optional.)* **Splunk (HEC)** - `TULIP_LOGGING_SPLUNK_URL=https://splunk.your-domain.com:8088/services/collector` - `TULIP_LOGGING_SPLUNK_TOKEN=<your_splunk_hec_token>` 1. Restart the Connector Host Restart the service so the new environment variables take effect. 1. Verify delivery Generate activity (e.g., run a connector function) and confirm logs appear in your destination: - **Datadog**: Check recent logs for your host/service name. - **Loki**: Query by host label or a known message substring in Grafana Explore. - **Splunk**: Search recent events from your host (e.g., `index=<your_index> source="tulip-connector-host"`). 1. Change or disable logging - To switch destinations, update the variables to the new provider (and remove the old ones). - To disable, remove the logging variables and restart the service. ### Additional information Implementation based on Grafana Alloy exporters: **Datadog exporter:** [https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.datadog/](https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.datadog/) **Splunk HEC exporter:** [https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.splunkhec/](https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.splunkhec/) ## Inbound and outbound call load This section explains how many HTTP requests the OPCH sends to the Tulip Cloud. These requests can be grouped into **fixed rate requests** (always running) and **variable rate requests** (dependent on your configuration and activity). ### Fixed rate requests These requests occur at a steady, predictable rate: | **Type** | **Rate** | **Description** | | --- | --- | --- | | **Heartbeat** | 6 requests/minute | Confirms that the OPCH is online and connected. | | **Data Source Polling** | 20 requests/minute | Regularly | | s for updates to configured data sources. | | | ### Variable rate requests These requests depend on your configuration and activity. The more changes or events happening, the higher the request rate. | **Type** | **Typical Rate** | | --- | --- | | **Machine Data Source Online Status Changes** | 1 request per change (up to 60 requests/minute) | | **Connector Calls** | 1 outgoing request for every HTTP connector call | ### Example calculation Consider a setup with: - **1 machine data source** - **500 machine attributes**, each reporting data at **1Hz** (once per second) **Worst-case request rate:** ``` `Rate (worst case) = (6 + 1 + 20) + 40 + 60 + 240 = 367 requests/minute ``` Note The configurations and online statuses typically change rarely. Also, the OPCH optimizes the number of HTTP requests to the Tulip cloud by batching multiple requests together when needed. As a result, the average rate for the above setup will likely be around `200-270 requests/minute`. ## Additional references ### Enable log-rotations for Docker For existing On-Premise Connector Hosts that are not using Docker log-rotations, follow the instructions documented [here](https://support.tulip.co/docs/enabling-log-rotations-for-existing-on-premise-connector-host-container) to ensure disk-space is properly maintained. ### Check your OPCH health To integrate the OPCH with your Azure or Kubernetes-based service orchestrator, you can use the following configuration: **For LTS16+ OPCH:** To integrate the OPCH with your Azure or Kubernetes-based service orchestrator, you can use the following configuration: The health check endpoint is randomly assigned on a port and exposed at the root path `/health-check`. Optionally the assigned port can be overridden by setting `TULIP_HEALTH_HTTP_PORT` to the specified port. For example: `TULIP_HEALTH_HTTP_PORT = 80`. A successful response will return an HTTP status code of `204`, indicating the OPCH service is healthy and operational. **For pre-LTS16 OPCH:** To integrate the OPCH with your Azure or Kubernetes-based service orchestrator, you can use the following configuration: The health check endpoint needs to be enabled by setting the environment variable: `CONNECTORS_HEALTHZ_SERVER_ENABLED` to `true`. The endpoint is available on port `9223` and exposed at the root path `/`. Optionally the default port `9223` can be overridden by setting `CONNECTORS_PORT` into the specified port. For example: `CONNECTORS_PORT = 80` A successful response will return an HTTP status code of `200 (OK)`, indicating the OPCH service is healthy and operational. Optionally the default port `9223` can be overridden by setting `CONNECTORS_PORT` into the specified port. For example: `CONNECTORS_PORT = 80 ` A successful response will return an HTTP status code of `200 (OK)`, indicating the OPCH service is healthy and operational. --- Did you find what you were looking for? You can also head to [community.tulip.co](https://community.tulip.co/?utm_source=intercom&utm_medium=article-link&utm_campaign=all) to post your question or see if others have solved a similar topic! **OPC-UA** **OPC Unified Architecture** is a cross-platform, open-source, IEC62541 standard for data exchange from sensors to cloud applications developed by the OPC Foundation. **Connector Host** Tulip **Connector Hosts** are designed to allow your Tulip Apps to interface with external systems such as databases, APIs, and machines. **On-Prem Connector Hosts** sit within your network and allow Tulip to interface with SQL databases and APIs that aren't accessible to the cloud.