S3

Keep project files and history in S3-compatible storage on a Kubernetes deployment.

Project files and their history are stored by the history-v1 service, template files by the filestore service, both inside every Ayakaleaf Pro pod. By default they write to the data volume; with S3 they write to buckets. Which buckets and permissions are needed is described in S3.

Services	history-v1 (project files and history), filestore (template files), in every Ayakaleaf Pro pod
Pod → S3	the S3 endpoint, for every file read or written
Required	for several replicas: their data volumes are not shared, the buckets are
Periodic jobs	none

Choose S3 before users create projects. An instance that already keeps files on its volume needs the S3 migration first.

Configuration

1. Buckets and keys

   Create the three buckets overleaf-template-files, overleaf-project-blobs and overleaf-chunks and the two restricted users with your S3 service as described in S3 setup, or run Garage in the cluster as shown below. Put the four keys into a Secret:

   kubectl -n overleaf create secret generic overleaf-s3 \
     --from-literal=OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID=<filestore key> \
     --from-literal=OVERLEAF_FILESTORE_S3_SECRET_ACCESS_KEY=<filestore secret> \
     --from-literal=OVERLEAF_HISTORY_S3_ACCESS_KEY_ID=<history key> \
     --from-literal=OVERLEAF_HISTORY_S3_SECRET_ACCESS_KEY=<history secret>
   
2. ConfigMap

   30-config.yaml (additions)

     OVERLEAF_FILESTORE_BACKEND: s3
     OVERLEAF_FILESTORE_TEMPLATE_FILES_BUCKET_NAME: overleaf-template-files
     OVERLEAF_FILESTORE_S3_REGION: eu-west-1
     OVERLEAF_HISTORY_BACKEND: s3
     OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET: overleaf-project-blobs
     OVERLEAF_HISTORY_CHUNKS_BUCKET: overleaf-chunks
     OVERLEAF_HISTORY_S3_REGION: eu-west-1
     # a self-hosted S3 service also needs its endpoint and path-style addressing
     # OVERLEAF_FILESTORE_S3_ENDPOINT: http://garage:3900
     # OVERLEAF_FILESTORE_S3_PATH_STYLE: "true"
     # OVERLEAF_HISTORY_S3_ENDPOINT: http://garage:3900
     # OVERLEAF_HISTORY_S3_PATH_STYLE: "true"
   
3. Add the Secret to the pod and restart

   In the Deployment (or StatefulSet), add the Secret next to the others:

             envFrom:
               - configMapRef: {name: overleaf-env}
               - secretRef: {name: overleaf-secrets}
               - secretRef: {name: overleaf-s3}
   

   kubectl apply -f 30-config.yaml -f 40-overleaf.yaml
   kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
   

Garage in the cluster

Without an S3 service, Garage is a small S3 server that runs in the cluster. The Horizontal scaling setup was tested with it. The commands below generate the keys and create the Secret overleaf-s3 themselves, so use them instead of the Secret command in step 1.

MinIO, used in Overleaf’s sample, no longer publishes container images: minio/minio is gone from Docker Hub and quay.io.

50-garage.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: garage-config
  namespace: overleaf
data:
  garage.toml: |
    metadata_dir = "/var/lib/garage/meta"
    data_dir = "/var/lib/garage/data"
    db_engine = "lmdb"
    replication_factor = 1
    rpc_bind_addr = "[::]:3901"
    rpc_public_addr = "127.0.0.1:3901"
    # rpc_secret and admin_token come from GARAGE_RPC_SECRET / GARAGE_ADMIN_TOKEN
    [s3_api]
    s3_region = "garage"          # Overleaf's OVERLEAF_*_S3_REGION must match
    api_bind_addr = "[::]:3900"
    [admin]
    api_bind_addr = "[::]:3903"
---
apiVersion: v1
kind: Service
metadata:
  name: garage
  namespace: overleaf
spec:
  selector:
    app: garage
  ports:
    - name: s3
      port: 3900
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: garage
  namespace: overleaf
spec:
  serviceName: garage
  replicas: 1
  selector:
    matchLabels:
      app: garage
  template:
    metadata:
      labels:
        app: garage
    spec:
      containers:
        - name: garage
          image: dxflrs/garage:v2.5.0
          env:
            - name: GARAGE_RPC_SECRET
              valueFrom: {secretKeyRef: {name: garage-secrets, key: rpc_secret}}
            - name: GARAGE_ADMIN_TOKEN
              valueFrom: {secretKeyRef: {name: garage-secrets, key: admin_token}}
          ports:
            - containerPort: 3900
          readinessProbe:
            tcpSocket:
              port: 3900
          resources:
            requests: {cpu: 50m, memory: 64Mi}
            limits: {memory: 512Mi}
          volumeMounts:
            - {name: config, mountPath: /etc/garage.toml, subPath: garage.toml}
            - {name: data, mountPath: /var/lib/garage}
      volumes:
        - name: config
          configMap:
            name: garage-config
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: [ReadWriteOnce]
        resources:
          requests:
            storage: 10Gi

Generate the secrets, start Garage, then create the layout, buckets and the two restricted keys. Garage key IDs are GK plus 24 hex characters, secrets 64 hex characters:

kubectl -n overleaf create secret generic garage-secrets \
  --from-literal=rpc_secret="$(openssl rand -hex 32)" \
  --from-literal=admin_token="$(openssl rand -base64 32)"
kubectl -n overleaf create secret generic overleaf-s3 \
  --from-literal=OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID="GK$(openssl rand -hex 12)" \
  --from-literal=OVERLEAF_FILESTORE_S3_SECRET_ACCESS_KEY="$(openssl rand -hex 32)" \
  --from-literal=OVERLEAF_HISTORY_S3_ACCESS_KEY_ID="GK$(openssl rand -hex 12)" \
  --from-literal=OVERLEAF_HISTORY_S3_SECRET_ACCESS_KEY="$(openssl rand -hex 32)"
kubectl apply -f 50-garage.yaml
kubectl -n overleaf rollout status statefulset/garage

g() { kubectl -n overleaf exec garage-0 -- /garage "$@"; }
s() { kubectl -n overleaf get secret overleaf-s3 -o jsonpath="{.data.$1}" | base64 -d; }
g layout assign -z dc1 -c 8G "$(g status 2>/dev/null | awk '/^[0-9a-f]{16}/{print $1; exit}')"
g layout apply --version 1
for b in overleaf-template-files overleaf-project-blobs overleaf-chunks; do g bucket create "$b"; done
g key import --yes -n overleaf-filestore "$(s OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID)" "$(s OVERLEAF_FILESTORE_S3_SECRET_ACCESS_KEY)"
g key import --yes -n overleaf-history "$(s OVERLEAF_HISTORY_S3_ACCESS_KEY_ID)" "$(s OVERLEAF_HISTORY_S3_SECRET_ACCESS_KEY)"
g bucket allow --read --write overleaf-template-files --key overleaf-filestore
g bucket allow --read overleaf-project-blobs --key overleaf-filestore
g bucket allow --read --write overleaf-project-blobs --key overleaf-history
g bucket allow --read --write overleaf-chunks --key overleaf-history

The permissions match the policies in S3. Garage checks the region: it is garage here, and OVERLEAF_*_S3_REGION must be the same.

With Garage, set the endpoint, PATH_STYLE: "true" and the region garage for both services in the ConfigMap, as in 60-config.yaml of Horizontal scaling.

Several replicas

All replicas must use the same buckets and keys. Back the buckets up with your S3 provider’s tools; the replicas’ own disks then hold no data that needs a backup.

Tested on Kubernetes

On Kubernetes 1.37 with three replicas and Garage as above, every end-to-end test of these pages that creates projects, uploads files, uses the history or publishes templates passed, and afterwards the buckets overleaf-project-blobs, overleaf-chunks and overleaf-template-files held the objects, while the replicas’ own /var/lib/overleaf/data/history stayed empty.