Skip to content

A local-first personal finance app

docs: add guidance on avoiding Nginx header collisions for COOP/COEP (#6477)

Herbert Kipkoech88fbfe707895
diff --git a/.github/actions/docs-spelling/expect.txt b/.github/actions/docs-spelling/expect.txt
index 71d3b8eb91..49ba4aa0a5 100644
--- a/.github/actions/docs-spelling/expect.txt
+++ b/.github/actions/docs-spelling/expect.txt
@@ -38,7 +38,9 @@ Cloudflare
CMCIFRPAXXX
COBADEFF
CODEOWNERS
+COEP
commerzbank
+COOP
Copiar
COUNTA
COUNTBLANK
diff --git a/packages/docs/docs/config/reverse-proxies.md b/packages/docs/docs/config/reverse-proxies.md
index b0c1682005..6d3c558bef 100644
--- a/packages/docs/docs/config/reverse-proxies.md
+++ b/packages/docs/docs/config/reverse-proxies.md
@@ -109,6 +109,31 @@ Please refer to the [official documentation](https://doc.traefik.io/traefik/user
## NGINX
+### Note on Cross-Origin Isolation & Header Collisions
+
+Actual Budget requires a "Secure Context" and specific headers (`COOP/COEP`) to enable `SharedArrayBuffer` for its underlying SQLite engine. While the application attempts to set these headers automatically, implementing a manual Nginx configuration as suggested above can lead to **duplicate headers** (e.g., `require-corp, require-corp`).
+
+Modern browsers will invalidate security policies if headers are duplicated, resulting in a `SharedArrayBufferMissing` fatal error.
+
+To resolve the "additional security mechanisms" mentioned in the note above, use the `proxy_hide_header` directive to ensure Nginx acts as the single source of truth:
+
+```nginx
+location / {
+ proxy_pass http://actual_server:5006;
+
+ # Prevents header duplication between Upstream and Proxy
+ proxy_hide_header Cross-Origin-Embedder-Policy;
+ proxy_hide_header Cross-Origin-Opener-Policy;
+
+ # Explicitly set mandatory security headers
+ add_header Cross-Origin-Embedder-Policy "require-corp" always;
+ add_header Cross-Origin-Opener-Policy "same-origin" always;
+ add_header Origin-Agent-Cluster "?1" always;
+
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+}
+```
The SSL certificate is issued by Let's Encrypt. The [Certbot](https://certbot.eff.org/instructions) tool provides options for automatic updating upon expiration.
At the very least you will need to adapt `server_name` and the `ssl_certificate/ssl_certificate_key` paths to match your setup.
Please refer to their [official documentation](https://nginx.org/en/docs/) for further details.