@@ -1,26 +1,95 @@
 ---
-description: Configure Aidbox to use a proxy for outgoing requests.
+description: Configure Aidbox to use a proxy for outgoing requests, install a corporate CA certificate, and troubleshoot SSL errors when fetching FHIR packages.
 ---
 
 # How to configure Aidbox to use a proxy for outgoing requests
 
 ## Objectives
 
-* Configure Aidbox to use a proxy for outgoing requests.
+* Route Aidbox outbound HTTP / HTTPS traffic through a corporate proxy.
+* Trust a corporate CA used for proxy SSL inspection.
+* Diagnose SSL errors when fetching FHIR packages from `fs.get-ig.org`.
+* Know which fallback to reach for in air-gapped environments.
 
 ## Before you begin
 
-* You must have an active proxy server.
+* You have a proxy host / port from your network team.
+* If the proxy performs SSL inspection, you have the corporate root CA certificate (`.crt` / `.pem`).
+* You can build a custom container image based on `healthsamurai/aidboxone`.
 
-## Configure Aidbox to use a proxy for outgoing requests
+## Configure the HTTP / HTTPS proxy
 
-To configure Aidbox to use a proxy for outgoing requests, you need to set the following environment variable:
+Aidbox uses Java's standard networking stack, so the proxy is configured through `JAVA_OPTS`. Set both `https.*` and `http.*` so package downloads, webhook deliveries, terminology lookups, and any other outbound calls go through the proxy.
 
 ```yaml
-JAVA_OPTS: -Dhttps.proxyHost=proxyhost -Dhttps.proxyPort=proxyPort
+# docker-compose.yaml
+services:
+  aidbox:
+    environment:
+      JAVA_OPTS: >-
+        -Dhttps.proxyHost=proxy.corp.example.com
+        -Dhttps.proxyPort=8080
+        -Dhttp.proxyHost=proxy.corp.example.com
+        -Dhttp.proxyPort=8080
+        -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.svc.cluster.local
 ```
-Please note that this configuration will proxy **all outbound** requests from Aidbox, including things like Subscriptions with webhook destinations.
 
-See also:
+{% hint style="warning" %}
+This setting proxies **all** outbound requests from Aidbox, including [AidboxTopicDestination](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md) webhook deliveries, GCP Pub/Sub clients, and external terminology calls. Add internal hosts you want to reach directly to `http.nonProxyHosts`.
+{% endhint %}
 
-* https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/doc-files/net-properties.html
+See [Java networking properties reference](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/doc-files/net-properties.html) for the full property list.
+
+## Install a corporate CA certificate
+
+If your proxy performs SSL inspection it presents an internally-signed certificate when Aidbox connects to `https://fs.get-ig.org` (or any other upstream). Java rejects it because the corporate root CA is not in the default truststore. Add the CA to the JVM's `cacerts` keystore at image build time:
+
+```dockerfile
+FROM healthsamurai/aidboxone:edge
+
+COPY corporate-ca.crt /tmp/corporate-ca.crt
+
+RUN keytool -importcert -trustcacerts \
+      -keystore "$JAVA_HOME/lib/security/cacerts" \
+      -storepass changeit -noprompt \
+      -alias corporate-ca \
+      -file /tmp/corporate-ca.crt \
+ && rm /tmp/corporate-ca.crt
+```
+
+If the proxy issues a chain (intermediate + root), import each certificate with a unique alias.
+
+{% hint style="info" %}
+Verify the certificate was added: `keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit -alias corporate-ca`.
+{% endhint %}
+
+## Troubleshooting SSL errors when fetching FHIR packages
+
+Since [Aidbox 2602](../../overview/release-notes.md#february-2026-2602) the HTTP client uses Java's standard JSSE SSL stack. JSSE is stricter than the previous client and surfaces certificate-chain problems that earlier versions silently tolerated.
+
+**Symptoms** — startup fails to bootstrap [`BOX_BOOTSTRAP_FHIR_PACKAGES`](../../reference/all-settings.md), or [Artifact Registry](../../artifact-registry/artifact-registry-overview.md) package install errors with one of:
+
+* `SSL peer shut down incorrectly`
+* `EOFException` thrown from `sun.security.ssl.SSLSocketInputRecord.read`
+* `unable to find valid certification path to requested target`
+* `PKIX path building failed`
+
+**Root cause** — corporate proxy SSL inspection presents a certificate signed by an internal CA that the JVM does not trust. The `fs.get-ig.org` certificate itself is healthy (Google Trust Services chain) — the failure is at the proxy hop, not at the upstream.
+
+**Fix order:**
+
+1. Confirm whether you are behind a proxy with SSL inspection: `openssl s_client -connect fs.get-ig.org:443 -servername fs.get-ig.org`. If the issuer is not Google Trust Services, the proxy is intercepting.
+2. Configure the proxy via `JAVA_OPTS` ([above](#configure-the-http-https-proxy)).
+3. If SSL inspection is enabled, install the corporate CA ([above](#install-a-corporate-ca-certificate)).
+4. As a workaround for air-gapped or otherwise restricted environments, skip the network entirely — see [Loading packages from local filesystem](../../artifact-registry/artifact-registry-overview.md#loading-packages-from-local-filesystem).
+5. Or point Aidbox at an internal package mirror (Verdaccio, Nexus, etc.) using [`BOX_FHIR_NPM_PACKAGE_REGISTRY`](../../reference/all-settings.md).
+
+{% hint style="danger" %}
+Disabling SSL verification (`-Dcom.sun.net.ssl.checkRevocation=false`, custom permissive truststores, etc.) silences the symptom but exposes Aidbox to MITM attacks on every outbound call. Fix the trust chain instead.
+{% endhint %}
+
+## See also
+
+* [Artifact Registry overview](../../artifact-registry/artifact-registry-overview.md)
+* [Loading packages from local filesystem](../../artifact-registry/artifact-registry-overview.md#loading-packages-from-local-filesystem)
+* [Java networking system properties](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/doc-files/net-properties.html)