> ## Documentation Index > Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Escalonamento horizontal > Execute várias réplicas do Ayakaleaf Pro atrás de um balanceador de carga com sessões persistentes (sticky sessions). Uma réplica usa a CPU de um único nó para cada compilação: nos nossos nós de teste com 2 vCPUs, seis compilações simultâneas levaram três vezes mais tempo que uma, enquanto os outros nós permaneciam ociosos. Várias réplicas distribuem os usuários, e suas compilações, entre os nós. Isto segue o design de [Escalabilidade horizontal](https://ayakaleaf-pro.mintlify.site/pt/on-premises/maintenance/horizontal-scaling.md) do Overleaf, adaptado ao Kubernetes: | Requisito | Aqui | | - | - | | MongoDB e Redis compartilhados | `10-mongo.yaml` e `20-redis.yaml` da instalação | | Segredos compartilhados | o Secret `overleaf-secrets` do [passo 2](https://ayakaleaf-pro.mintlify.site/pt/on-premises/installation/using-kubernetes/2.-create-the-namespace-and-secrets.md) já os contém | | Arquivos e histórico dos projetos no **S3** (não NFS) | qualquer serviço S3, consulte [S3](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/kubernetes/s3.md); o Garage aparece lá como exemplo dentro do cluster | | Um disco local por réplica para compilações e uploads | `hostPath` `/srv/overleaf-ha` em cada nó | | Roteamento persistente, WebSockets, timeouts de 10 min, uploads de 50 MB | HAProxy com a configuração de exemplo do Overleaf | | git-bridge como instância única ao lado de uma réplica | git-bridge com `overleaf-0` como seu par | > [!WARNING] > > Planeje o S3 desde o início. Uma instância que já mantém arquivos em seu volume precisa primeiro da [migração para S3](https://ayakaleaf-pro.mintlify.site/pt/on-premises/maintenance/s3-migration.md). Esta configuração substitui o Deployment do passo 5: exclua-o (`kubectl delete -f 40-overleaf.yaml`) antes de aplicar o StatefulSet. **1. Armazenamento S3** Configure os três buckets e os dois usuários conforme descrito em [S3](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/kubernetes/s3.md), com o seu serviço S3 ou com o Garage no cluster, e coloque as quatro chaves no Secret `overleaf-s3`. A configuração abaixo usa o exemplo do Garage daquela página. **2. Configuração** Este ConfigMap substitui `30-config.yaml`. Ele adiciona o S3 e o git-bridge e aponta `OVERLEAF_SITE_URL` para o balanceador de carga: ```yaml title="60-config.yaml" wrap theme={null} 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: admin@example.com # 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. Réplicas** ```yaml title="70-overleaf.yaml" wrap theme={null} 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, não Deployment.** Cada réplica recebe um nome estável (`overleaf-0`, `overleaf-1`, ...) ao qual o cookie do balanceador de carga e o git-bridge se referem, e `OrderedReady` inicia primeiro apenas `overleaf-0`, de modo que somente uma réplica executa as migrações do banco de dados. * **Uma réplica por nó.** Cada réplica inicia suas compilações pelo Docker do seu nó e as mantém em `/srv/overleaf-ha` do seu nó. * **`V1_HISTORY_URL` por réplica.** Cada réplica fornece links de histórico com seu próprio nome, para que o git-bridge possa alcançá-los. **4. git-bridge** ```yaml title="75-git-bridge.yaml" wrap theme={null} 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 ``` Consulte [Integração com Git](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/kubernetes/integrations/git-integration.md) para saber por que `GIT_BRIDGE_HOST` é um endereço IP fixo. **5. Balanceador de carga** A configuração do HAProxy é o exemplo do Overleaf com cinco alterações: `/project//mcp` roteado para `overleaf-0` como `/git/` (consulte [Servidor MCP](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/kubernetes/integrations/mcp-server.md#several-replicas)), HTTP simples na porta `8080` (a imagem é executada como um usuário não root, que não pode usar a porta 80 sob o containerd), servidores encontrados pelo DNS do cluster (os IPs dos pods mudam a cada reinicialização), um DaemonSet para que todos os nós respondam e `balance leastconn` em vez do padrão `roundrobin` (consulte o Q\&A abaixo). ```yaml title="80-haproxy.yaml" wrap theme={null} 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} ``` ```bash theme={null} 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` mantém os endereços IP dos usuários em `X-Forwarded-For`. **6. TLS** Termine o HTTPS no HAProxy conforme descrito em [Proxy TLS](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/kubernetes/tls-proxy.md) e, em seguida, defina `OVERLEAF_SITE_URL` com o endereço `https://` e `OVERLEAF_SECURE_COOKIE: "true"` em `60-config.yaml`. ### O que esperar Testamos três réplicas em três nós com 2 vCPUs e 4 GB cada, com MongoDB, Redis, Garage, git-bridge e HAProxy nos mesmos nós: * 12 usuários compilando um documento de 600 páginas ao mesmo tempo: todos os 12 compilaram e obtiveram seu PDF, 4 usuários por réplica; uma rodada levou de 8 a 18 segundos. Cada nó manteve pelo menos 1,3 GB de memória disponível. * Cada usuário permanece em uma réplica (cookie `server-pro-ha`), incluindo o download do PDF, que precisa vir da réplica que o compilou. O mesmo vale via HTTPS, incluindo o WebSocket do editor. * Quando uma réplica para, seus usuários recebem erros por cerca de 15 a 20 segundos, até que o HAProxy a marque como fora do ar; então eles passam para outra réplica e permanecem conectados, porque as sessões ficam no Redis. ### Q\&A > [accordion] Por que `balance leastconn`? > > **Resposta:** Com o exemplo do Overleaf (`roundrobin`, um HAProxy por nó), 12 novos usuários ficaram distribuídos em 8, 3 e 1 nas três réplicas no nosso teste, e a réplica mais ocupada fez os usuários mais lentos esperarem 29 segundos. Com `leastconn`, que prefere a réplica com menos conexões abertas (cada editor mantém um WebSocket aberto), o mesmo teste resultou em 4, 4 e 4 e 18 segundos. A persistência de sessão não muda: ela vem do cookie. > [accordion] Posso usar meu ingress controller em vez do HAProxy? > > **Resposta:** Sim, se ele rotear por um cookie para uma réplica estável, suportar WebSockets, permitir tempos de requisição de 10 minutos e uploads de 50 MB, mantiver seu timeout de keep-alive abaixo de 65 segundos, enviar `X-Forwarded-For` e `X-Forwarded-Proto` e enviar `/git/` e `/project//mcp` para `overleaf-0`. Roteie para os nomes próprios das réplicas (`overleaf-N.overleaf-hl`), não para um Service que balanceia cada requisição. > [accordion] Como adiciono uma quarta réplica? > > **Resposta:** Adicione um nó com Docker e as imagens do TeX Live, defina `replicas: 4` em `70-overleaf.yaml` e adicione uma linha `server overleaf-3 ...` à configuração do HAProxy (e incremente `config-hash` para que o HAProxy reinicie). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.