grist-backup

A minimal, reliable backup utility for Grist cloud/self-hosted workspaces. Runs in a Docker container, periodically downloads all documents from all workspaces, and keeps only the latest N backups.

Features

• Backs up all documents from all workspaces in a Grist organization
• Stores backups in a structured folder tree by date and workspace
• Retains only the latest N backup sets (automatic rotation)
• No cron needed: runs in a loop inside the container
• Healthcheck and log rotation included
• Lightweight Alpine-based image

Usage

1. Configuration (Environment Variables)

Variable	Example	Description
GRIST_HOST	gristlabs.getgrist.com	Grist instance FQDN
GRIST_ORG	myteam or 42	Organization slug or ID
GRIST_API_KEY	secret_xxx	Grist API key
BACKUP_DIR	/data	Directory for backups
BACKUP_INTERVAL_H	8	Backup interval (hours)
BACKUP_KEEP	5	How many backup sets to keep

2. Folder Structure

Backups are stored as:

/data/YYYYmmdd/<workspace_name>/<document_name>.grist

Oldest backup sets are deleted automatically.

3. Docker Compose Example

version: "3.8"
services:
  grist-backup:
    build: .
    restart: unless-stopped
    environment:
      GRIST_HOST: "gristlabs.getgrist.com"
      GRIST_ORG: "myteam"
      GRIST_API_KEY: "secret_xxx"
      BACKUP_DIR: "/data"
      BACKUP_INTERVAL_H: "8"
      BACKUP_KEEP: "5"
    volumes:
      - ./data:/data
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "sh", "-c", "ls /data/$$(date -u +%Y%m%d)/*/*.grist 1>/dev/null 2>&1"]
      interval: 1h
      timeout: 10s
      retries: 3

4. Build and Run

docker-compose build
docker-compose up -d

5. Healthcheck

Container is healthy if at least one backup file exists for today.

6. Notes

• For self-hosted Grist, use your own host and API key.
• Log rotation and healthcheck are enabled by default.
• Backup rotation is by date (not per-document).

---

MIT License