Appwrite Self-Hosted SDK Endpoint and Reverse-Proxy TLS: Which Hostname Must Match?

Answer to the Core Question

When a self‑hosted Appwrite deployment terminates TLS on an external reverse proxy, the certificate presented by that proxy must include the hostname that SDK clients use in the endpoint URL. If the SDK is configured to call https://app.example.com/v1, the Subject Alternative Name (SAN) of the proxy’s certificate must contain app.example.com (or a wildcard that covers it). The internal hostname or IP that the Appwrite containers use—such as appwrite.internal or 172.18.0.2—does not need to appear in the SAN.

Why the External Hostname Matters

• The SDK’s HTTP client validates the server certificate against the hostname it connects to.
• Appwrite does not expose any SDK‑specific certificate validation settings; it relies on the platform’s default trust store.
• If the proxy uses SNI or a wildcard certificate, ensure the SAN covers all aliases that SDK clients might use.

Trusting Self‑Signed Certificates

The only supported path for self‑signed certificates is to add the CA that signed the proxy’s cert to the client’s trust store. Appwrite SDKs do not provide a configuration option to skip or override certificate verification.

1. Generate or obtain the CA that signed the proxy’s cert.
2. On the client machine, add the CA to the trusted store:

   # Linux (Debian/Ubuntu)
   sudo cp my-proxy-ca.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates
   
   # macOS
   sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain my-proxy-ca.crt
   

3. Verify the certificate chain from the proxy:

   openssl s_client -connect app.example.com:443 -showcerts
   

   Check that the SAN includes app.example.com.
4. Run a simple SDK request and confirm success.

Distinguishing DNS vs TLS Handshake Failures

When a client cannot resolve the SDK endpoint, the connection attempt fails before any TLS handshake. Typical exceptions include UnknownHostException or the string "Name or service not known". In contrast, a TLS handshake failure—caused by a hostname mismatch or an untrusted cert—emits an SSL/TLS exception such as SSLHandshakeException or the message "CERTIFICATE_VERIFY_FAILED".

To test this distinction:

1. Point the SDK endpoint to an unknown hostname (e.g., https://bogus.example.com) and record the error.
2. Use a valid hostname but point the proxy to a cert that does not match the hostname or is signed by an untrusted CA, and record the error.

Examining the exception class or the error string in the SDK log will tell you whether the problem is DNS resolution or TLS verification.

Missing Diagnostic Detail?

If you are using a wildcard certificate or SNI with multiple hostnames, let me know the exact SAN entries you have configured. That will help confirm whether all SDK aliases are covered.