Why Grist Belongs on Your Own Server
Grist sits in a category that very few tools actually occupy: it works like a spreadsheet on the surface, but underneath it operates as a relational database. That combination makes it genuinely useful for managing structured data that would break apart in a standard spreadsheet or feel overcomplicated in a full SQL setup.
What You Are Actually Getting With Grist
Before running any commands, it helps to understand what Grist does differently. A standard spreadsheet treats every sheet as an independent grid. Grist lets you link tables together so that a row in one table can reference rows in another – the same way a database uses foreign keys. You can then build custom views, form inputs, and filtered displays on top of those linked tables, all without writing a single line of SQL.
The self-hosted version of Grist is called Grist Core. It is the open-source release that the company behind Grist maintains on GitHub. The managed cloud version includes some enterprise features that are not in the open-source build, but for personal use, team wikis, project tracking, CRM-style contact lists, or inventory management, Grist Core covers everything you will realistically need.
Grist stores its data in SQLite files by default, which keeps the setup simple and makes backups straightforward – you are just copying a file. For larger deployments or multi-user environments where simultaneous writes become a concern, Grist also supports PostgreSQL as a backend. Most self-hosters running it for personal or small-team use will never need to switch away from SQLite.
The tool also ships with a Python-based formula engine. Formulas in Grist columns look familiar if you have used Excel or Google Sheets, but they can also reference related records from linked tables directly in a cell expression. That feature alone closes a lot of the gap between “spreadsheet” and “database” without requiring you to think in terms of joins or queries.
Installing and Configuring Grist Core With Docker
Docker is the most practical way to run Grist Core. The official image is maintained at gristlabs/grist on Docker Hub and gets updated regularly alongside the main codebase. If you already run other self-hosted services in containers – whether that is something like Wallos for subscription tracking or any other Docker-based app – Grist fits right into the same workflow.
Start by pulling the image and running a basic container to confirm everything works before you move to a production configuration. The minimal Docker command looks like this:
- Image: gristlabs/grist
- Port mapping: 8484:8484 (Grist listens on 8484 by default)
- Volume: mount a local directory to /persist inside the container – this is where Grist stores your SQLite database files and configuration
- Environment variable: set GRIST_SESSION_SECRET to a long random string – without this, sessions will not persist across container restarts
Once the container is running, open a browser and navigate to http://localhost:8484. You should see the Grist welcome screen. By default, Grist Core runs without authentication, meaning anyone who can reach the port can access it. That is fine for local development but not acceptable if the service is exposed on a network. To lock it down, you have two main options: put Grist behind a reverse proxy like Nginx or Caddy with HTTP basic authentication, or enable Grist’s built-in authentication support.
For authentication, Grist Core supports OpenID Connect, which lets you integrate it with identity providers like Keycloak, Authentik, or even a Google OAuth application. The relevant environment variables are GRIST_OIDC_IDP_ISSUER, GRIST_OIDC_IDP_CLIENT_ID, and GRIST_OIDC_IDP_CLIENT_SECRET. Set these alongside your provider’s discovery URL and Grist will redirect unauthenticated users to your login page before granting access. For a single-user personal server, the simpler path is to set GRIST_SINGLE_ORG to a workspace name and use the reverse proxy for basic auth – fewer moving parts.
If you are running Grist with Docker Compose, a minimal working configuration file would define the service with the gristlabs/grist image, map port 8484, bind the persist volume, and declare the session secret and any authentication variables in an environment block. Keep your Docker Compose file in a dedicated directory alongside a .env file that holds the secret values. This keeps credentials out of version control if you ever push your infrastructure config to a repository. After docker compose up -d, the container runs detached and will restart automatically on server reboot if you include restart: unless-stopped in the service definition.
Building Your First Document and Understanding the Data Model
Grist organizes everything into documents. A document is roughly equivalent to a single workbook in Excel – it contains multiple tables, views, and linked pages. When you create a new document, Grist opens an empty table. You define column types explicitly: text, numeric, date, reference, or choice list, among others. The Reference column type is where Grist separates itself from ordinary spreadsheets. When you set a column to reference another table, each cell in that column holds a link to a specific row in the target table, and you can then pull any field from that linked row directly into a formula.
A practical starting point is a simple project tracker: one table for projects, one for tasks, with the tasks table referencing the projects table. Once the reference is set up, you can create a page layout that shows a list of projects on the left and a filtered task view on the right, where clicking a project automatically filters the task list to show only related rows. Grist calls this a linked section layout, and building it requires no code – just drag, drop, and configure the filter in the panel on the right side of the editor.
Backups in Grist are straightforward because of the SQLite file structure. Each document is a single .grist file inside your persist directory. Copying that file gives you a complete snapshot. You can schedule a cron job to copy the persist directory to another location, push it to an S3-compatible bucket, or simply include it in your regular server backup routine. Grist also has a built-in document history feature that tracks every change as a snapshot, accessible directly from the document menu, though this history lives inside the same file rather than in a separate location – making that external backup still the more reliable safety net.
