fix: configure zero-cache sync workers, connection limits, and publication

docker/.env.example

@@ -79,6 +79,23 @@ EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 # Change ZERO_ADMIN_PASSWORD for security in production.
 
 # ZERO_ADMIN_PASSWORD=surfsense-zero-admin
+
+# Publication restricting which tables zero-cache replicates from Postgres.
+# Created automatically by Alembic migration 116.
+# Only change this if you manage publications manually.
+# ZERO_APP_PUBLICATIONS=zero_publication
+
+# Sync worker tuning — zero-cache defaults ZERO_NUM_SYNC_WORKERS to the number
+# of CPU cores, which can exceed the connection pool limits on high-core machines.
+# Each sync worker needs at least 1 connection from both the UPSTREAM and CVR
+# pools, so these constraints must hold:
+#   ZERO_UPSTREAM_MAX_CONNS >= ZERO_NUM_SYNC_WORKERS
+#   ZERO_CVR_MAX_CONNS      >= ZERO_NUM_SYNC_WORKERS
+# Default of 4 workers is sufficient for self-hosted / personal use.
+# ZERO_NUM_SYNC_WORKERS=4
+# ZERO_UPSTREAM_MAX_CONNS=20
+# ZERO_CVR_MAX_CONNS=30
+
 # Full override for the Zero → Postgres connection URLs.
 # Leave commented out to use the Docker-managed `db` container (default).
 # ZERO_UPSTREAM_DB=postgresql://surfsense:surfsense@db:5432/surfsense