Self-Hosting Grist on a VPS: Open-Source Airtable Alternative

Google Sheets is a spreadsheet: it stores data flat, calculations are limited to sheet functions, and relations between sheets rely on fragile VLOOKUPs. Airtable solves this with relational bases but at $20 per user per month, the bill adds up fast for an agency or technical team.

Grist combines both worlds: a familiar spreadsheet interface over a real relational database. Each document contains tables with typed columns (text, numeric, date, reference, attachment), explicit relations between tables via reference columns, and Python formulas that run server-side — not in the browser. On your VPS, Grist costs $0 extra per month.

A VPS with at least 1 GB of RAM and Docker installed is sufficient to get started. Grist deploys as a single gristlabs/grist container bundling Node.js (web server), Python (formula sandbox) and SQLite (document storage). A named volume /persist stores .grist files — one file per document. No external service required: no PostgreSQL, no Redis, no Celery.

The default port is 8484. Verify it is reachable from localhost before configuring the reverse proxy (curl -sI http://localhost:8484/).

Grist replaces fragile Google Sheets VLOOKUPs with reference columns and typed lookup functions. In an Orders table with a Customer column of type Reference → Customers, accessing the customer name is simply $Customer.Name — no VLOOKUP needed.

For aggregations, Grist provides lookupRecords() and lookupOne():

# In the Customers table — total order amount for a customer
SUM(Orders.lookupRecords(Customer=$id).Amount)

# In the Orders table — retrieve the customer's postal code
Customers.lookupOne(Name=$Customer.Name).PostalCode

# Progressive reduction using standard Python
import datetime
delay = (datetime.date.today() - $OrderDate).days
$Amount * (1 - 0.02 * delay // 30)

Python formulas run inside a gVisor sandbox (GRIST_SANDBOX_FLAVOR=gvisor): the Python process has no access to the filesystem or network, isolating computations even in multi-tenant contexts.

By default, GRIST_DEFAULT_EMAIL automatically logs in a single user without a password — sufficient for solo use or a trusted team on a private network. For multi-user deployments with real authentication, Grist supports OpenID Connect (OIDC) with Authentik, Keycloak, Google Workspace or any compatible provider.

Add these variables to the Compose file:

environment:
  GRIST_OIDC_IDP_ISSUER: "https://auth.yourdomain.com/application/o/grist/"
  GRIST_OIDC_IDP_CLIENT_ID: "your-client-id"
  GRIST_OIDC_IDP_CLIENT_SECRET: "your-client-secret"
  GRIST_OIDC_IDP_SCOPES: "openid email profile"
  GRIST_OIDC_SP_HOST: "https://grist.yourdomain.com"

Remove GRIST_DEFAULT_EMAIL once OIDC is configured — the two variables are incompatible. The first user to log in via OIDC becomes the site administrator.

Grist documents live in the Docker volume grist_data, under /persist/docs/. Two complementary strategies:

Volume snapshot (full backup, recommended): mount /persist/docs/ in a Backrest job (available in the ServOrbit catalogue). Backrest snapshots the folder via restic and pushes encrypted increments to S3, Backblaze B2 or SFTP — without stopping Grist.

# Emergency manual backup
docker run --rm \
  -v grist_data:/source:ro \
  -v /backups/grist:/dest \
  alpine tar czf /dest/grist-$(date +%Y%m%d).tar.gz -C /source .

Per-document export: in Grist, go to Document → Export → .grist (native SQLite format) or CSV/XLSX per table. The .grist export is sufficient to migrate a single document to another instance.

Grist also keeps a per-document snapshot history (Document → History) — useful for restoring a previous version without leaving the interface, up to the configured retention limit.

Container keeps restarting: check the logs (docker compose logs grist). The most common cause is an empty or too-short GRIST_SESSION_SECRET — it must be at least 32 hexadecimal characters. Also check volume permissions: docker exec grist ls -la /persist.

CORS errors on the API: if you call /api/docs/… from a different domain, add GRIST_ALLOWED_HOSTS=grist.yourdomain.com and make sure APP_HOME_URL matches the public URL exactly (with https://, no trailing slash).

Slowness on large datasets: Grist re-evaluates all formulas on every change. On tables with more than 100,000 rows, limit lookupRecords() to indexed columns and avoid Python formulas with heavy imports in trigger columns. The GRIST_MAX_ROWS_PER_TABLE variable (unbounded by default) allows setting a preventive limit.

Access issues after domain change: update APP_HOME_URL, clear browser cookies and restart the container. Active sessions use the old URL and become invalid.