Advanced configuration

Self-hosted Ocean integrations often run behind a load balancer, a corporate proxy, or a firewall. This page describes the settings that control how the integration is exposed on the network and how it sends requests to Port and to the third-party tool.

Integration endpoints

An Ocean integration runs an HTTP server, on port 8000 by default (APPLICATION__PORT environment variable). It exposes the following endpoints:

Endpoint	Description
GET /health/live	Liveness check. Returns 200 while the integration process is running.
GET /health/ready	Readiness check. Returns 503 until the integration finishes starting up, then 200.
GET /metrics	Prometheus metrics for the integration's resyncs. Populated when OCEAN__METRICS__ENABLED is true.
/integration/*	The integration's live events endpoints.
POST /resync	Triggers a resync. Exposed only when using the WEBHOOK event listener.

Both health endpoints return a JSON body that includes the integration's Ocean core version, for example:

{
  "status": "healthy",
  "check": "ready",
  "core_version": "0.52.3"
}

Use /health/ready for Kubernetes readiness probes, so traffic is routed to the pod only after it has started, and /health/live for liveness probes.

Base URL and path prefix

Variable	Description	Default
OCEAN__BASE_URL	The public URL of the integration. Required for live events, since the integration uses it to register webhooks in the third-party tool.	-
OCEAN__PATH_PREFIX	A prefix added to the integration's health, metrics, and live events endpoints. Use it when the integration is served under a sub-path of a shared host.	-

For example, with OCEAN__PATH_PREFIX=/github, the readiness endpoint becomes /github/health/ready, and the prefix is appended to the base URL used for webhooks.

When OCEAN__BASE_URL is not set, the integration does not process live events, and data is updated only by resyncs.

Deprecated setting

OCEAN__INTEGRATION__CONFIG__APP_HOST is deprecated. Use OCEAN__BASE_URL instead.

Ocean uses the HTTPX client for HTTP requests, so the standard HTTPX environment variables apply to it.

Proxy configuration

Use the following environment variables to route the integration's requests through a proxy server:

Variable	Description
HTTP_PROXY	The proxy URL for HTTP requests.
HTTPS_PROXY	The proxy URL for HTTPS requests.
ALL_PROXY	The proxy URL for all requests.
NO_PROXY	A comma-separated list of hostnames or URLs that bypass the proxy.

For example:

HTTP_PROXY=http://my-proxy.com:1111
HTTPS_PROXY=http://my-proxy.com:2222
NO_PROXY=127.0.0.1,internal.example.com

For more details, see the HTTPX proxy documentation.

Custom certificates

Use the following environment variables when the integration needs to trust a private certificate authority (CA), for example one used by an SSL inspection proxy or a self-hosted tool:

Variable	Description
SSL_CERT_FILE	The path to a file containing a bundle of trusted CA certificates in PEM format.
SSL_CERT_DIR	The path to a directory containing trusted CA certificate files.
SSLKEYLOGFILE	The path to a file where TLS key information is logged. Use it only for debugging, to decrypt traffic with tools such as Wireshark.

For example:

SSL_CERT_FILE=/path/to/cacert.pem

For more details, see the HTTPX SSL documentation.

Ocean SSL verification settings

Ocean provides separate TLS verification settings for traffic to Port's API and traffic to third-party APIs (GitLab, Jira, GitHub, and others).

These settings are useful when your CA is trusted, but Python 3.13+ still rejects the certificate because of its strict X.509 rules. This commonly happens behind SSL inspection proxies that issue certificates without an Authority Key Identifier.

Variable	Default	Applies to
OCEAN__SSL__PORT__VERIFY	true	Port's API.
OCEAN__SSL__PORT__X509__STRICT	true	Port's API.
OCEAN__SSL__THIRD_PARTY__VERIFY	true	Third-party APIs.
OCEAN__SSL__THIRD_PARTY__X509__STRICT	true	Third-party APIs.

The combination of the two settings determines the behavior:

verify	x509.strict	Behavior
true	true	Default. Full certificate validation, the same as standard Python TLS.
true	false	Validates the certificate chain and hostname, but relaxes Python 3.13+ strict X.509 checks.
false	Ignored	Disables all TLS verification. Use only as a temporary last resort.

If TLS to a third-party API fails behind a firewall that re-signs certificates, start with:

OCEAN__SSL__THIRD_PARTY__X509__STRICT=false

Change the Port API settings only if requests to Port also fail.

Security considerations

• If your private CA is not in the system trust store, configure SSL_CERT_FILE or SSL_CERT_DIR first. The Ocean SSL settings do not replace trusting your CA.
• Prefer x509.strict=false over verify=false, which disables all protection. Do not use verify=false in production without your security team's approval.
• Ocean logs a warning at startup whenever a non-default SSL setting is active.

Supported integrations

The OCEAN__SSL__THIRD_PARTY__* settings apply to integrations that use Ocean's built-in HTTP client, including GitLab, GitHub, Jira, Azure DevOps, and Snyk.

They do not apply to integrations that use a vendor SDK (AWS, Azure, GCP, Kafka, New Relic, and the deprecated GitLab integration), to the No-code Ocean custom integration, which has its own verify_ssl setting, or to ArgoCD when allow_insecure is set to true.

HTTP client timeouts and retries

Ocean's built-in HTTP client handles timeouts and retries for requests to Port and to third-party APIs.

• Timeout - Each request times out after OCEAN__CLIENT_TIMEOUT seconds (default 60).
• Retried status codes - 401, 408, 429, 502, 503, and 504. Integrations can add status codes specific to their API.
• Retried methods - Only idempotent methods: GET, HEAD, PUT, DELETE, OPTIONS, and TRACE. POST and PATCH requests are not retried.
• Backoff - Up to 10 attempts with exponential backoff and jitter, waiting at most 60 seconds between attempts.
• Rate limits - When the response includes a Retry-After or x-ratelimit-reset header, Ocean waits for the time it specifies instead of the default backoff.
• Network errors - Connection errors and timeouts are retried the same way.

If requests to a slow self-hosted tool time out, increase OCEAN__CLIENT_TIMEOUT.

Outbound IP blocker

To protect against server-side request forgery (SSRF), Ocean can block requests whose host resolves to a non-public IP address. This includes private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback, link-local addresses such as cloud metadata endpoints, and carrier-grade NAT ranges. Port's own domains and the APIs of supported third-party SaaS tools are always allowed.

Installation	Default
Hosted by Port	Enabled. Integrations hosted by Port cannot reach tools on private networks. To integrate with a tool on your private network, self-host the integration.
Self-hosted	Disabled. The integration can reach any address its network allows.

To enable the blocker on a self-hosted integration, set OCEAN__DISABLE_IP_OUTBOUND_BLOCKER=false. Blocked requests fail with an error stating that the host IP address is not within the allowed ranges.

Streaming large responses

Some integrations can stream large API responses to disk instead of loading them into memory, which reduces the integration's memory usage. Streaming is used only by integrations that support it, currently ArgoCD, and is disabled by default.

Variable	Description	Default
OCEAN__STREAMING__ENABLED	Whether to stream large responses to disk.	false
OCEAN__STREAMING__CHUNK_SIZE	The size of each chunk read from the response, in bytes.	65536 (64 KB)
OCEAN__STREAMING__MAX_BUFFER_SIZE_MB	The maximum size of the in-memory buffer used while parsing, in bytes despite its name.	20971520 (20 MB)
OCEAN__STREAMING__LOCATION	The directory where streamed data is temporarily stored. Data is encrypted on disk and deleted after it is read.	/tmp/ocean/streaming