Deploying an Insight Point using the install script
Generic instructions for running an Insight Point as a Docker container on Linux.
Veza maintains a script you can use to quickly install and run an Insight Point with Docker. Follow these steps to set up your environment, run the latest install script, and manage the deployment.
The Insight Point installation script includes automatic features to reduce manual configuration steps:
Proxy Inheritance: HTTP proxy settings from the host environment are automatically applied to new installations
Certificate Detection: Host certificate bundles are automatically detected and mounted for new installations
Enhanced Connectivity Feedback: Improved connectivity testing includes proxy information display and dedicated status scripts
Note: Feature availability may vary by Veza release version. Some automatic features apply to new installations and may require reinstallation for existing Insight Points.
Prerequisites
Time Synchronization
Ensure your host system has accurate time synchronization before installation:
# Verify time synchronization status
timedatectl status
# If NTP is not synchronized, enable it
sudo timedatectl set-ntp trueThe Insight Point inherits time settings from the host system. Ensure the host maintains accurate time synchronization to prevent workflow timeouts or connectivity issues.
System Requirements
Systemd
Docker (or Podman with Docker compatibility)
System resources meeting the Insight Point requirements (minimum: 2 CPU cores, 4 GB RAM)
Install Docker
Install
Generate an Insight Point key from the Veza Integrations > Insight Point page. Store it as an environment variable before downloading and executing the script:
or
Setting a custom instance ID for High Availability deployments
Instance ID is required in High Availability deployments where multiple instances of Insight Points are being installed with the same INSIGHT_POINT_KEY. Instance ID must be unique for each Insight Point instance. By default, the Insight Point uses "default" as the instance ID. To specify a custom instance ID, set the INSTANCE_ID environment variable:
or
Setting tags during installation
Tags are custom key-value labels that help organize and categorize your Insight Point instances. For an overview of tags, their use cases, and requirements, see Tags in the main Insight Point documentation.
To set tags during installation, use the INSIGHT_POINT_TAGS environment variable with a comma-separated list of key:value pairs:
or
Post-Installation
The Insight Point automatically performs a connectivity test when the container starts. Recent enhancements provide improved feedback:
HTTP proxy information is now included in connectivity test output for easier debugging
Connectivity test results are available via the status script for streamlined troubleshooting
Viewing Connectivity Results:
The connectivity test output includes connection status to your Veza tenant, HTTP proxy information (if configured), certificate bundle configuration status, and any connectivity issues or configuration recommendations.
Remove
Uninstall
Uninstall will remove all components of the Insight Point but will not remove the configuration in /etc/veza-insight-point.
Remove
Remove will remove all components of the Insight Point and the configuration in /etc/veza-insight-point. The Insight Point Key will be lost (if not backed up).
Advanced Configuration
Pull from a different registry
The Insight Point image must be pulled from a pull-through cache or private registry (where the image is mirrored). You can override the image repository with the IMAGE_REPOSITORY config setting.
Create or edit the configuration in /etc/veza-insight-point/service.env to set the IMAGE_REPOSITORY configuration:
If pulling some other image version than the default image tag (latest), you need to configure the override using the IMAGE_TAG option:
After the changes have been made and saved, restart the Insight Point service:
Check that the service has started successfully by running the following command:
Configuring Instance ID
To manually configure the instance ID after installation, create or edit the configuration file /etc/veza-insight-point/config.env and add:
After making configuration changes, restart the Insight Point service:
Configuring Tags
To manually configure tags after installation, create or edit the configuration file /etc/veza-insight-point/config.env and add:
After making configuration changes, restart the Insight Point service:
Removing abandoned Insight Point instances
When you install an Insight Point, it registers itself with the Veza control plane using the provided Insight Point Key and instance ID ("default" if not provided). This allows the control plane to track the instance's status and connectivity. You can list all instances for each configured Insight Point in the Veza Integrations > Insight Point page.
Important: If an Insight Point instance is abandoned (no longer in use and uninstalled), you should manually remove it from the Insight Point in the Veza Integrations > Insight Point page. This ensures the control plane stops tracking the instance's status and prevents it from affecting Insight Point's overall status your monitoring dashboard.
Using a proxy server
Automatic Proxy Detection (Recommended)
For new Insight Point installations, HTTP proxy settings are automatically inherited from the host system's HTTP_PROXY environment variable. This eliminates the need for manual proxy configuration in most environments.
To verify automatic proxy detection is working:
Ensure the host system has
HTTP_PROXYset in the environmentRun the installation script
Check the connectivity test output for proxy information
Manual Proxy Configuration
If you need to use a different proxy configuration or disable automatic detection, you can manually configure proxy settings.
To disable automatic proxy inheritance, create or edit /etc/veza-insight-point/config.env and add:
To manually configure proxy settings, add these lines to /etc/veza-insight-point/config.env:
Proxy Information Display
Connectivity tests display current proxy configuration details including:
Current proxy configuration being used by the Insight Point
Whether proxy settings were inherited from the host or manually configured
Any proxy-related connectivity issues
To configure custom certificates, see the Using custom certificates section.
After making configuration changes, restart the Insight Point service:
Check that the service has started successfully by running the following command:
Configuring Insight Point to forward connections to Veza (early access)
An Insight Point can proxy connections to Veza, allowing you to send Open Authorization API (OAA) payloads to a locally accessible server within a VPC instead of directly over the internet.
When a proxy port is enabled in the configuration, applications can push to the Insight Point's internal network address (e.g., http://localhost:8080/api/v1/providers/custom/...), instead of making API calls directly to Veza's cloud service (https://$VEZA_URL/api/v1/providers/custom/...).
Create or edit the configuration file /etc/veza-insight-point/service.env to set the proxy port:
Save the changes. Then, restart the Insight Point service:
Proxy server is supported since Veza release 2025.5.x. For older Insight Points, you will need to reinstall before you can enable a proxy port:
Using custom certificates
The Insight Point runs as a Docker container, which means it is isolated from the host operating system, including its truststore.
Certificates your host trusts (such as a Zscaler or corporate CA) are invisible to the container by default.
The certificate configuration below tells the Insight Point which certificate bundle to copy into the container at startup so it can trust your internal services and proxies.
Automatic Certificate Bundle Detection (Recommended)
For new Insight Point installations, the install script automatically detects and configures the host's CA certificate bundle. During installation, the script scans the following standard locations in order and uses the first file it finds:
/etc/ssl/certs/ca-certificates.crt
Debian, Ubuntu
/etc/pki/tls/certs/ca-bundle.crt
RHEL, CentOS
/etc/ssl/ca-bundle.pem
OpenSUSE
/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
RHEL (modern)
/etc/ssl/cert.pem
Other distributions
When a bundle is detected, the install script reports the path and (in interactive mode) prompts you to confirm, override, or skip it. The chosen path is saved to /etc/veza-insight-point/service.env as CA_BUNDLE_PATH.
Enterprise certificate management (Zscaler, etc.): If your organization uses a tool like Zscaler, it typically injects its CA certificate into the host's system bundle at one of the paths above. As long as that bundle exists at a standard path and is current, automatic detection will pick it up with no extra configuration.
Verifying certificate detection
To confirm the certificate bundle is configured and being used:
A non-empty result (e.g., CA_BUNDLE_PATH=/etc/ssl/certs/ca-certificates.crt) means the bundle is configured. When the service starts, you will also see this line in the logs:
If the line reads Using default CA bundle instead, no custom bundle is mounted — the container is using only its built-in certificates.
Adding a certificate to a running Insight Point
If the Insight Point is already running but a new CA certificate needs to be trusted, such as when an internal service starts using a new CA, or an enterprise proxy certificate is rotated, you can update the host's system truststore and restart the service. No changes to the Insight Point configuration are needed if CA_BUNDLE_PATH already points to the correct bundle file.
The Insight Point reads the bundle from CA_BUNDLE_PATH and copies it into the container on each service start. Restarting after updating the host bundle is all that is required.
Step 1: Add the CA certificate to the host trust store
Step 2: Restart the Insight Point
Step 3: Confirm the updated bundle is in use
The output should show Using CA bundle from <path>. If TLS errors persist after restarting, re-run the truststore update command from Step 1 to confirm the certificate is present. On Debian and Ubuntu, the output will include 0 added, 0 removed; done if the certificate is already in the store. On RHEL, CentOS, and OpenSUSE, update-ca-trust produces no output on success.
Manual Certificate Configuration
If automatic detection did not find the right bundle (e.g., your CA bundle is in a non-standard location), set CA_BUNDLE_PATH directly in /etc/veza-insight-point/service.env:
For example, if your Zscaler or corporate CA bundle is at a custom path:
After making configuration changes, restart the Insight Point service:
Confirm the bundle is now being used by checking the startup log:
Disabling certificate mounting
To run the Insight Point without mounting any custom certificate bundle (not recommended in environments with private CAs):
Webhook Relay Configuration
The webhook relay service allows the Insight Point to forward webhook requests to destinations in your private network. For an overview of webhook relay, when to use it, security considerations, and supported host formats, see Webhook Relay in the main Insight Point documentation.
Configuration During Installation
To enable webhook relay during initial installation, set the environment variables before running the install script:
Or in a single command:
Manual Configuration
To configure webhook relay on an existing Insight Point installation, edit the configuration file:
Add or update the following lines:
To disable webhook relay:
After making configuration changes, restart the Insight Point service:
Verifying Webhook Relay Configuration
To verify webhook relay is configured correctly:
Check the configuration file:
Inspect the container environment variables:
Use the status script:
If webhook relay is enabled but not working:
Verify the allowed hosts are in the correct format
Check that the destination is included in the allowed hosts list
Review the Insight Point logs for validation or connection errors
Ensure the destination is actually reachable from the Insight Point's network
Troubleshooting
Status Script (Recommended)
The Insight Point installation includes a dedicated status script for health checking without requiring log inspection. This script is the recommended first step for troubleshooting.
Run the status script to check Insight Point health:
The status script checks:
Service Status: Whether the Insight Point service is running
Health Endpoint: Whether the service is responding to health checks
Connectivity Test: Network connectivity to your Veza tenant
Configuration: Current proxy and certificate settings
This script provides immediate feedback on common issues and is ideal for iterative troubleshooting when making configuration changes.
Service Status
Retrieve the status of the Insight Point systemd service:
Connectivity Testing
Connectivity test results are displayed in the terminal. For ongoing troubleshooting, use the status script above or check recent logs for connectivity information.
Logs
For detailed troubleshooting when the status script indicates issues, examine the service logs:
Retrieve last 500 log lines for the Insight Point service:
Follow logs for the Insight Point service:
Reinstall
Reinstall will remove the currently installed Insight Point service and install it again. All configuration in /etc/veza-insight-point will be preserved.
Tips & Best Practices
Using the Status Script for Iterative Troubleshooting
When configuring proxy settings or troubleshooting connectivity issues, use the status script to quickly verify changes without examining logs:
This approach is much faster than manually inspecting service logs and provides immediate feedback on whether configuration changes are working.
When Manual Configuration is Still Needed
While automatic features handle most scenarios, manual configuration may be required for:
Custom Proxy Settings: When the desired proxy differs from the host's
HTTP_PROXYsettingSpecific Certificate Bundles: When using certificates in non-standard locations
Enterprise Environments: Where automatic detection may not work due to security policies
Legacy Installations: Older Insight Points may not have all automatic features
Troubleshooting Automatic Features
If automatic proxy or certificate detection isn't working:
Check the connectivity test output for configuration details
Verify the host system's environment variables (
echo $HTTP_PROXY)Use the status script to see current configuration
Fall back to manual configuration if needed
Last updated
Was this helpful?