Horisontell skalning

Kör flera Ayakaleaf Pro-repliker bakom en lastbalanserare med sticky sessions.

En replik använder processorn i en enda nod för varje kompilering: på våra testnoder med 2 vCPU:er tog sex samtidiga kompileringar tre gånger så lång tid som en, medan de andra noderna stod sysslolösa. Flera repliker sprider användarna, och deras kompileringar, över noderna.

Detta följer Overleafs design för Horisontell skalning, översatt till Kubernetes:

Krav	Här
Delad MongoDB och Redis	10-mongo.yaml och 20-redis.yaml från installationen
Delade hemligheter	Secret overleaf-secrets från steg 2 innehåller dem redan
Projektfiler och historik i S3 (inte NFS)	valfri S3-tjänst, se S3; där finns Garage som exempel inom klustret
En lokal disk per replik för kompileringar och uppladdningar	hostPath /srv/overleaf-ha på varje nod
Beständig routning, WebSockets, 10 min timeouts, 50 MB uppladdningar	HAProxy med Overleafs exempelkonfiguration
git-bridge som singleton bredvid en replik	git-bridge med overleaf-0 som syskon

Planera för S3 från början. En instans som redan har filer på sin volym behöver först genomgå S3-migreringen. Den här konfigurationen ersätter Deployment från steg 5: ta bort den (kubectl delete -f 40-overleaf.yaml) innan du tillämpar StatefulSet.

1. S3-lagring

   Konfigurera de tre buckets och två användare som beskrivs i S3, med din S3-tjänst eller med Garage i klustret, och lägg de fyra nycklarna i Secret overleaf-s3. Konfigurationen nedan använder Garage-exemplet från den sidan.

2. Konfiguration

   Den här ConfigMap ersätter 30-config.yaml. Den lägger till S3 och git-bridge och pekar OVERLEAF_SITE_URL mot lastbalanseraren:

   60-config.yaml

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: overleaf-env
     namespace: overleaf
   data:
     OVERLEAF_APP_NAME: Ayakaleaf Pro
     OVERLEAF_SITE_URL: http://192.0.2.10:30081      # the load balancer (HAProxy) URL
     OVERLEAF_ADMIN_EMAIL: [e-mail]
     # Emails: add the sender and the SMTP server together, see Email delivery
     OVERLEAF_MONGO_URL: mongodb://mongo-0.mongo:27017,mongo-1.mongo:27017,mongo-2.mongo:27017/sharelatex?replicaSet=overleaf
     OVERLEAF_REDIS_HOST: redis
     REDIS_HOST: redis
     ENABLED_LINKED_FILE_TYPES: project_file,project_output_file,url
     ENABLE_CONVERSIONS: "true"
     EMAIL_CONFIRMATION_DISABLED: "true"
     OVERLEAF_TRUSTED_PROXY_IPS: loopback,10.244.0.0/16   # HAProxy runs in the pod CIDR
     # Sandboxed compiles, node paths: each replica owns /srv/overleaf-ha on its node
     SANDBOXED_COMPILES: "true"
     SANDBOXED_COMPILES_SIBLING_CONTAINERS: "true"
     DOCKER_RUNNER: "true"
     SANDBOXED_COMPILES_HOST_DIR_COMPILES: /srv/overleaf-ha/data/compiles
     SANDBOXED_COMPILES_HOST_DIR_OUTPUT: /srv/overleaf-ha/data/output
     SANDBOXED_COMPILES_HOST_DIR_CACHE: /srv/overleaf-ha/data/cache
     ALL_TEX_LIVE_DOCKER_IMAGES: ghcr.io/ayaka-notes/texlive-full:2026.1
     ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: TeX Live 2026
     TEX_LIVE_DOCKER_IMAGE: ghcr.io/ayaka-notes/texlive-full:2026.1
     # S3 (required for more than one replica); keys are in the Secret overleaf-s3
     OVERLEAF_FILESTORE_BACKEND: s3
     OVERLEAF_FILESTORE_TEMPLATE_FILES_BUCKET_NAME: overleaf-template-files
     OVERLEAF_FILESTORE_S3_ENDPOINT: http://garage:3900
     OVERLEAF_FILESTORE_S3_PATH_STYLE: "true"
     OVERLEAF_FILESTORE_S3_REGION: garage
     OVERLEAF_HISTORY_BACKEND: s3
     OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET: overleaf-project-blobs
     OVERLEAF_HISTORY_CHUNKS_BUCKET: overleaf-chunks
     OVERLEAF_HISTORY_S3_ENDPOINT: http://garage:3900
     OVERLEAF_HISTORY_S3_PATH_STYLE: "true"
     OVERLEAF_HISTORY_S3_REGION: garage
     # Git integration: one git-bridge, its sibling is overleaf-0
     GIT_BRIDGE_ENABLED: "true"
     GIT_BRIDGE_HOST: 10.96.100.80      # the git-bridge Service's fixed ClusterIP, see 75-git-bridge.yaml
     GIT_BRIDGE_PORT: "8000"
   
3. Repliker

   70-overleaf.yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: overleaf-hl
     namespace: overleaf
   spec:
     clusterIP: None            # stable DNS per replica: overleaf-0.overleaf-hl, ...
     selector:
       app: overleaf-ha
     ports:
       - {name: http, port: 80}
       - {name: web, port: 3000}       # git-bridge API (sibling only)
       - {name: history, port: 3100}   # history-v1, used by git-bridge via V1_HISTORY_URL
   ---
   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: overleaf
     namespace: overleaf
   spec:
     serviceName: overleaf-hl
     replicas: 3
     # OrderedReady: overleaf-0 runs the migrations alone before the next replica starts
     podManagementPolicy: OrderedReady
     selector:
       matchLabels:
         app: overleaf-ha
     template:
       metadata:
         labels:
           app: overleaf-ha
       spec:
         terminationGracePeriodSeconds: 60
         # Keep the environment to the ConfigMap and Secrets: no REDIS_PORT=tcp://..., GIT_BRIDGE_PORT=tcp://...
         enableServiceLinks: false
         affinity:
           podAntiAffinity:            # one replica per node: each uses that node's Docker and disk
             requiredDuringSchedulingIgnoredDuringExecution:
               - labelSelector:
                   matchLabels:
                     app: overleaf-ha
                 topologyKey: kubernetes.io/hostname
         containers:
           - name: sharelatex
             image: ghcr.io/ayaka-notes/overleaf-pro:6.3.2
             env:
               - name: POD_NAME
                 valueFrom:
                   fieldRef:
                     fieldPath: metadata.name
               # Each replica hands out history URLs with its own stable name, so git-bridge can reach them
               - name: V1_HISTORY_URL
                 value: http://$(POD_NAME).overleaf-hl.overleaf.svc.cluster.local:3100/api
             envFrom:
               - configMapRef: {name: overleaf-env}
               - secretRef: {name: overleaf-secrets}
               - secretRef: {name: overleaf-s3}
             ports:
               - containerPort: 80
             readinessProbe:
               httpGet: {path: /status, port: 80}
               periodSeconds: 10
             resources:
               requests: {cpu: 500m, memory: 1536Mi}
               limits: {memory: 3Gi}
             volumeMounts:
               - {name: local, mountPath: /var/lib/overleaf}
               - {name: docker-sock, mountPath: /var/run/docker.sock}
         volumes:
           # Local disk for ephemeral files (compiles, output, uploads); the HOST_DIR_* paths are under it
           - name: local
             hostPath: {path: /srv/overleaf-ha, type: DirectoryOrCreate}
           - name: docker-sock
             hostPath: {path: /var/run/docker.sock, type: Socket}
   

   • StatefulSet, inte Deployment. Varje replik får ett stabilt namn (overleaf-0, overleaf-1, …) som lastbalanserarens cookie och git-bridge hänvisar till, och OrderedReady startar overleaf-0 ensam först, så att bara en replik kör databasmigreringarna.
   • En replik per nod. Varje replik startar sina kompileringar via sin nods Docker och sparar dem i sin nods /srv/overleaf-ha.
   • V1_HISTORY_URL per replik. Varje replik delar ut historiklänkar med sitt eget namn, så att git-bridge kan nå dem.
4. git-bridge

   75-git-bridge.yaml

   apiVersion: v1
   kind: Service
   metadata:
     name: git-bridge
     namespace: overleaf
   spec:
     # Fixed ClusterIP (inside the service CIDR): the sharelatex image's nginx proxies /git/ with
     # `resolver 127.0.0.11` (Docker's DNS), which does not exist in Kubernetes, so GIT_BRIDGE_HOST is this IP
     clusterIP: 10.96.100.80
     selector:
       app: git-bridge
     ports:
       - {name: http, port: 8000}
   ---
   apiVersion: apps/v1
   kind: StatefulSet
   metadata:
     name: git-bridge
     namespace: overleaf
   spec:
     serviceName: git-bridge
     replicas: 1
     selector:
       matchLabels:
         app: git-bridge
     template:
       metadata:
         labels:
           app: git-bridge
       spec:
         # Service "git-bridge" would inject GIT_BRIDGE_PORT=tcp://..., which git-bridge reads as its port
         enableServiceLinks: false
         containers:
           - name: git-bridge
             image: ghcr.io/ayaka-notes/overleaf-pro/git-bridge:6.3.2   # same version as the sharelatex image
             command: ["/server-pro-start.sh"]
             securityContext:
               runAsUser: 0
             env:
               - {name: GIT_BRIDGE_API_BASE_URL, value: "http://overleaf-0.overleaf-hl.overleaf.svc.cluster.local:3000/api/v0/"}
               - {name: GIT_BRIDGE_OAUTH2_SERVER, value: "http://overleaf-0.overleaf-hl.overleaf.svc.cluster.local"}
               - {name: GIT_BRIDGE_POSTBACK_BASE_URL, value: "http://git-bridge.overleaf.svc.cluster.local:8000"}
               - {name: GIT_BRIDGE_ROOT_DIR, value: /data/git-bridge}
             ports:
               - containerPort: 8000
             resources:
               requests: {cpu: 100m, memory: 256Mi}
               limits: {memory: 768Mi}
             volumeMounts:
               - {name: data, mountPath: /data/git-bridge}
     volumeClaimTemplates:
       - metadata:
           name: data
         spec:
           accessModes: [ReadWriteOnce]
           resources:
             requests:
               storage: 5Gi
   

   Se Git-integration för varför GIT_BRIDGE_HOST är en fast IP-adress.

5. Lastbalanserare

   HAProxy-konfigurationen är Overleafs exempel med fem ändringar: /project/<id>/mcp dirigeras till overleaf-0 precis som /git/ (se MCP-server), vanlig HTTP på port 8080 (avbildningen körs som en användare som inte är root, vilken inte kan binda port 80 under containerd), servrar som hittas via kluster-DNS (poddarnas IP-adresser ändras vid varje omstart), en DaemonSet så att varje nod svarar, och balance leastconn i stället för standardvärdet roundrobin (se Frågor och svar nedan).

   80-haproxy.yaml

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: haproxy-config
     namespace: overleaf
   data:
     haproxy.cfg: |
       global
         log stdout format raw local0 info
   
       resolvers kubedns
         parse-resolv-conf
         hold valid 10s
   
       defaults
         mode                    http
         # New sessions go to the replica with the fewest open connections (editors keep a WebSocket open)
         balance                 leastconn
         option                  httpchk HEAD /status
         http-check              expect status 200
         default-server          check resolvers kubedns init-addr none
         log                     global
         option                  httplog
         # Reroute to a different backend if the sticky one is down
         option                  redispatch 1
         retries                 3
         # Sticky session for 24h of inactivity -- compile output is deleted after 24h
         cookie                  server-pro-ha insert maxidle 24h
         timeout queue           1m
         timeout connect         15s
         timeout client          1m
         # Allow slow compiles -- hard-coded limit in clsi is 10min
         timeout server          10m
         # Disconnect the editor after 23h
         timeout tunnel          23h
         # Lower than NGINX_KEEPALIVE_TIMEOUT (65s) in the sharelatex container
         timeout http-keep-alive 60s
   
       listen overleaf
         bind :8080
         option forwardfor
         # When TLS ends in front of HAProxy, also pass:  http-request set-header X-Forwarded-Proto https
         # git requests go to the git-bridge sibling
         use-server overleaf-0 if { path_beg /git/ }
         # MCP clients send no cookie: keep compile, log and PDF download on one replica
         use-server overleaf-0 if { path_reg ^/project/[0-9a-f]{24}/mcp(/|$) }
         http-response add-header X-Served-By %s
         stats enable
         stats uri /haproxy
         server overleaf-0 overleaf-0.overleaf-hl.overleaf.svc.cluster.local:80 cookie overleaf-0
         server overleaf-1 overleaf-1.overleaf-hl.overleaf.svc.cluster.local:80 cookie overleaf-1
         server overleaf-2 overleaf-2.overleaf-hl.overleaf.svc.cluster.local:80 cookie overleaf-2
   ---
   apiVersion: apps/v1
   # DaemonSet: one HAProxy per node, so the NodePort answers on every node with externalTrafficPolicy
   # Local. The cookie holds the replica name, so stickiness works whichever HAProxy a request hits.
   kind: DaemonSet
   metadata:
     name: haproxy
     namespace: overleaf
   spec:
     selector:
       matchLabels:
         app: haproxy
     template:
       metadata:
         labels:
           app: haproxy
         annotations:
           config-hash: "1"   # bump to restart after editing the ConfigMap
       spec:
         containers:
           - name: haproxy
             image: haproxy:lts-alpine
             ports:
               - containerPort: 8080
             resources:
               requests: {cpu: 50m, memory: 32Mi}
               limits: {memory: 256Mi}
             volumeMounts:
               - {name: config, mountPath: /usr/local/etc/haproxy}
         volumes:
           - name: config
             configMap:
               name: haproxy-config
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: haproxy
     namespace: overleaf
   spec:
     type: NodePort
     externalTrafficPolicy: Local    # keep the client IP (no SNAT); only nodes running HAProxy answer
     selector:
       app: haproxy
     ports:
       - {name: http, port: 80, targetPort: 8080, nodePort: 30081}
   

   kubectl delete -f 40-overleaf.yaml --ignore-not-found
   kubectl apply -f 60-config.yaml -f 70-overleaf.yaml -f 75-git-bridge.yaml -f 80-haproxy.yaml
   kubectl -n overleaf rollout status statefulset/overleaf --timeout=20m
   curl -sI http://192.0.2.10:30081/login | grep -i x-served-by
   

   externalTrafficPolicy: Local behåller användarnas IP-adresser i X-Forwarded-For.

6. TLS

   Avsluta HTTPS i HAProxy enligt beskrivningen i TLS-proxy och sätt sedan OVERLEAF_SITE_URL till https://-adressen och OVERLEAF_SECURE_COOKIE: "true" i 60-config.yaml.

​

Vad du kan förvänta dig

Vi testade tre repliker på tre noder med 2 vCPU:er och 4 GB vardera, med MongoDB, Redis, Garage, git-bridge och HAProxy på samma noder:

• 12 användare som kompilerade ett 600-sidigt dokument samtidigt: alla 12 kompilerade och hämtade sin PDF, 4 användare per replik; en omgång tog 8 till 18 sekunder. Varje nod hade minst 1,3 GB minne tillgängligt.
• Varje användare stannar på en replik (cookie server-pro-ha), inklusive PDF-nedladdningen som måste komma från repliken som kompilerade den. Detsamma gäller över HTTPS, inklusive redigerarens WebSocket.
• När en replik stoppas får dess användare fel i ungefär 15 till 20 sekunder, tills HAProxy markerar den som nere; sedan flyttas de till en annan replik och förblir inloggade, eftersom sessionerna finns i Redis.

​

Frågor och svar

Varför balance leastconn?

Svar: Med Overleafs exempel (roundrobin, en HAProxy per nod) fördelades 12 nya användare som 8, 3 och 1 på de tre replikerna i vårt test, och den mest belastade repliken fick de långsammaste användarna att vänta 29 sekunder. Med leastconn, som föredrar repliken med minst antal öppna anslutningar (varje redigerare håller en WebSocket öppen), gav samma test 4, 4 och 4 och 18 sekunder. Sessionsbindningen (stickiness) är oförändrad: den kommer från cookien.

Kan jag använda min ingress-controller i stället för HAProxy?

Svar: Ja, om den dirigerar via en cookie till en stabil replik, stöder WebSockets, tillåter förfrågningstider på 10 minuter och uppladdningar på 50 MB, håller sin keep-alive-timeout under 65 sekunder, skickar X-Forwarded-For och X-Forwarded-Proto, och skickar /git/ och /project/<id>/mcp till overleaf-0. Dirigera till replikernas egna namn (overleaf-N.overleaf-hl), inte till en Service som lastbalanserar varje förfrågan.

Hur lägger jag till en fjärde replik?

Svar: Lägg till en nod med Docker och TeX Live-avbildningarna, sätt replicas: 4 i 70-overleaf.yaml och lägg till en rad server overleaf-3 ... i HAProxy-konfigurationen (och öka config-hash så att HAProxy startas om).