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
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:
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
Automatic Certificate Bundle Detection (Recommended)
For new Insight Point installations, the system automatically detects and mounts the host's certificate bundle to the container. This removes the manual certificate configuration step for properly configured hosts, such as those using Zscaler or other enterprise certificate management systems.
The automatic certificate detection locates the host system's certificate bundle and mounts it to the Insight Point container. This works with common enterprise certificate management solutions and eliminates manual certificate configuration in most environments.
Manual Certificate Configuration
If automatic certificate detection doesn't work for your environment or you need to use a specific certificate bundle, you can manually configure certificates.
Create or edit the configuration file /etc/veza-insight-point/service.env to mount custom certificates to the Insight Point container:
For custom certificate bundle locations, adjust the path accordingly:
After making configuration changes, restart the Insight Point service:
Check that the service has started successfully by running the following command:
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?