feat: add Zero infra — docker-compose, env vars, Dockerfile, CI workflows

- Add zero-cache service to docker-compose.yml and docker-compose.dev.yml
- Add ZERO_* env vars to docker/.env.example
- Add NEXT_PUBLIC_ZERO_CACHE_URL to surfsense_web/.env.example
- Add NEXT_PUBLIC_ZERO_CACHE_URL placeholder ARG/ENV to Dockerfile
- Add NEXT_PUBLIC_ZERO_CACHE_URL runtime substitution to docker-entrypoint.js
- Add NEXT_PUBLIC_ZERO_CACHE_URL build arg to docker-build.yml and desktop-release.yml

.github/workflows/desktop-release.yml

@@ -57,6 +57,7 @@ jobs:
         working-directory: surfsense_web
         env:
           NEXT_PUBLIC_FASTAPI_BACKEND_URL: ${{ vars.NEXT_PUBLIC_FASTAPI_BACKEND_URL }}
+          NEXT_PUBLIC_ZERO_CACHE_URL: ${{ vars.NEXT_PUBLIC_ZERO_CACHE_URL }}
           NEXT_PUBLIC_DEPLOYMENT_MODE: ${{ vars.NEXT_PUBLIC_DEPLOYMENT_MODE }}
           NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE: ${{ vars.NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE }}
 

.github/workflows/docker-build.yml

@@ -164,6 +164,7 @@ jobs:
             ${{ matrix.image == 'web' && 'NEXT_PUBLIC_FASTAPI_BACKEND_URL=__NEXT_PUBLIC_FASTAPI_BACKEND_URL__' || '' }}
             ${{ matrix.image == 'web' && 'NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=__NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE__' || '' }}
             ${{ matrix.image == 'web' && 'NEXT_PUBLIC_ETL_SERVICE=__NEXT_PUBLIC_ETL_SERVICE__' || '' }}
+            ${{ matrix.image == 'web' && 'NEXT_PUBLIC_ZERO_CACHE_URL=__NEXT_PUBLIC_ZERO_CACHE_URL__' || '' }}
             ${{ matrix.image == 'web' && 'NEXT_PUBLIC_DEPLOYMENT_MODE=__NEXT_PUBLIC_DEPLOYMENT_MODE__' || '' }}
 
       - name: Export digest

docker/.env.example

@@ -35,6 +35,7 @@ EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 
 # BACKEND_PORT=8929
 # FRONTEND_PORT=3929
+# ZERO_CACHE_PORT=5929
 # SEARXNG_PORT=8888
 # FLOWER_PORT=5555
 
@@ -69,7 +70,20 @@ EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 # NEXT_FRONTEND_URL=https://app.yourdomain.com
 # BACKEND_URL=https://api.yourdomain.com
 # NEXT_PUBLIC_FASTAPI_BACKEND_URL=https://api.yourdomain.com
+# NEXT_PUBLIC_ZERO_CACHE_URL=https://zero.yourdomain.com
 
+# ------------------------------------------------------------------------------
+# Zero-cache (real-time sync)
+# ------------------------------------------------------------------------------
+# Defaults work out of the box for Docker deployments.
+# Change ZERO_ADMIN_PASSWORD for security in production.
+
+# ZERO_ADMIN_PASSWORD=surfsense-zero-admin
+# 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
+# ZERO_CVR_DB=postgresql://surfsense:surfsense@db:5432/surfsense
+# ZERO_CHANGE_DB=postgresql://surfsense:surfsense@db:5432/surfsense
 
 # ------------------------------------------------------------------------------
 # Database (defaults work out of the box, change for security)

docker/docker-compose.dev.yml

@@ -169,6 +169,28 @@ services:
   #     - redis
   #     - celery_worker
 
+  zero-cache:
+    image: rocicorp/zero:0.26.2
+    ports:
+      - "${ZERO_CACHE_PORT:-4848}:4848"
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      - ZERO_UPSTREAM_DB=${ZERO_UPSTREAM_DB:-postgresql://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}?sslmode=${DB_SSLMODE:-disable}}
+      - ZERO_CVR_DB=${ZERO_CVR_DB:-postgresql://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}?sslmode=${DB_SSLMODE:-disable}}
+      - ZERO_CHANGE_DB=${ZERO_CHANGE_DB:-postgresql://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}?sslmode=${DB_SSLMODE:-disable}}
+      - ZERO_REPLICA_FILE=/data/zero.db
+      - ZERO_ADMIN_PASSWORD=${ZERO_ADMIN_PASSWORD:-surfsense-zero-admin}
+    volumes:
+      - zero_cache_data:/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:4848/keepalive"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
   frontend:
     build:
       context: ../surfsense_web
@@ -176,6 +198,7 @@ services:
         NEXT_PUBLIC_FASTAPI_BACKEND_URL: ${NEXT_PUBLIC_FASTAPI_BACKEND_URL:-http://localhost:8000}
         NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE: ${NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE:-LOCAL}
         NEXT_PUBLIC_ETL_SERVICE: ${NEXT_PUBLIC_ETL_SERVICE:-DOCLING}
+        NEXT_PUBLIC_ZERO_CACHE_URL: ${NEXT_PUBLIC_ZERO_CACHE_URL:-http://localhost:${ZERO_CACHE_PORT:-4848}}
         NEXT_PUBLIC_DEPLOYMENT_MODE: ${NEXT_PUBLIC_DEPLOYMENT_MODE:-self-hosted}
     ports:
       - "${FRONTEND_PORT:-3000}:3000"
@@ -184,6 +207,8 @@ services:
     depends_on:
       backend:
         condition: service_healthy
+      zero-cache:
+        condition: service_healthy
 
 volumes:
   postgres_data:
@@ -194,3 +219,5 @@ volumes:
     name: surfsense-dev-redis
   shared_temp:
     name: surfsense-dev-shared-temp
+  zero_cache_data:
+    name: surfsense-dev-zero-cache

surfsense_web/.env.example

@@ -1,6 +1,7 @@
 NEXT_PUBLIC_FASTAPI_BACKEND_URL=http://localhost:8000
 NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=LOCAL or GOOGLE
 NEXT_PUBLIC_ETL_SERVICE=UNSTRUCTURED or LLAMACLOUD or DOCLING
+NEXT_PUBLIC_ZERO_CACHE_URL=http://localhost:4848
 
 # Contact Form Vars - OPTIONAL
 DATABASE_URL=postgresql://postgres:[YOUR-PASSWORD]@db.sdsf.supabase.co:5432/postgres

surfsense_web/Dockerfile

@@ -35,11 +35,13 @@ RUN corepack enable pnpm
 ARG NEXT_PUBLIC_FASTAPI_BACKEND_URL=__NEXT_PUBLIC_FASTAPI_BACKEND_URL__
 ARG NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=__NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE__
 ARG NEXT_PUBLIC_ETL_SERVICE=__NEXT_PUBLIC_ETL_SERVICE__
+ARG NEXT_PUBLIC_ZERO_CACHE_URL=__NEXT_PUBLIC_ZERO_CACHE_URL__
 ARG NEXT_PUBLIC_DEPLOYMENT_MODE=__NEXT_PUBLIC_DEPLOYMENT_MODE__
 
 ENV NEXT_PUBLIC_FASTAPI_BACKEND_URL=$NEXT_PUBLIC_FASTAPI_BACKEND_URL
 ENV NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE=$NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE
 ENV NEXT_PUBLIC_ETL_SERVICE=$NEXT_PUBLIC_ETL_SERVICE
+ENV NEXT_PUBLIC_ZERO_CACHE_URL=$NEXT_PUBLIC_ZERO_CACHE_URL
 ENV NEXT_PUBLIC_DEPLOYMENT_MODE=$NEXT_PUBLIC_DEPLOYMENT_MODE
 
 COPY --from=deps /app/node_modules ./node_modules

surfsense_web/docker-entrypoint.js

@@ -22,6 +22,7 @@ const replacements = [
 		process.env.NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE || "LOCAL",
 	],
 	["__NEXT_PUBLIC_ETL_SERVICE__", process.env.NEXT_PUBLIC_ETL_SERVICE || "DOCLING"],
+	["__NEXT_PUBLIC_ZERO_CACHE_URL__", process.env.NEXT_PUBLIC_ZERO_CACHE_URL || "http://localhost:4848"],
 	["__NEXT_PUBLIC_DEPLOYMENT_MODE__", process.env.NEXT_PUBLIC_DEPLOYMENT_MODE || "self-hosted"],
 ];