Grist

Grist (serviceId gristlabs-grist-core) is an open source relational spreadsheet server (grist-core, license Apache-2.0): a spreadsheet interface with database-style tables, typed columns and linked tables. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.

What it can do

  • Build documents with typed columns, linked tables and Python formulas that recalculate when data changes.
  • Create dashboards with linked widgets (charts, cards, calendars, summary tables) and custom views.
  • Import and export data (CSV, Excel, Google Drive, Airtable import), and use a REST API with webhooks.
  • Restrict access with rules down to rows, columns and tables, and collaborate with comments.
  • Store documents in a portable SQLite-based format.

Creating an instance

Grist on OSC needs two dependencies, created first and confirmed running (wait-for-service-ready or get-instance-status): * PostgreSQL (birme-osc-postgresql) for users, workspaces and document metadata. Connection URL form: postgres://user:password@host:port/grist. Only postgres:// and postgresql:// are supported; port defaults to 5432 and database name to grist. * An S3-compatible bucket for the document files, for example MinIO (minio-minio, see Service: MinIO). Create a bucket for Grist documents and enable versioning on it, otherwise Grist stops at startup with a fatal error. For OSC MinIO the access key is the RootUser and the secret key is the RootPassword.

Use describe-service-instance on the dependencies to read addresses and credentials. Store sensitive values as service secrets with create-service-secret (serviceId gristlabs-grist-core): for example griststdb (PostgreSQL URL), grists3access, grists3secret. Then call create-service-instance with serviceId: "gristlabs-grist-core":

{
  "name": "mygrist",
  "DatabaseUrl": "{{secrets.griststdb}}",
  "S3Endpoint": "https://<tenant>-guide.minio-minio.auto.prod-se.osaas.io",
  "S3Bucket": "grist-docs",
  "S3AccessKey": "{{secrets.grists3access}}",
  "S3SecretKey": "{{secrets.grists3secret}}",
  "AdminEmail": "admin@example.com"
}

Once running, open /login once on the instance URL to sign in as the user set in AdminEmail; that user is the default user and the installation admin. There is no default password and no built-in username/password pair.

Equivalent OSC CLI usage:

osc create gristlabs-grist-core mygrist \
  -o DatabaseUrl="{{secrets.griststdb}}" \
  -o S3Endpoint="https://<tenant>-guide.minio-minio.auto.prod-se.osaas.io" \
  -o S3Bucket="grist-docs" \
  -o S3AccessKey="{{secrets.grists3access}}" \
  -o S3SecretKey="{{secrets.grists3secret}}" \
  -o AdminEmail="admin@example.com"

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore (^\w+$); OSC limits names to 20 characters.
DatabaseUrl Yes string, sensitive PostgreSQL connection URL for Grist's home database (users, workspaces, document metadata), e.g. postgres://user:password@host:5432/grist. Only postgres:// or postgresql:// work; port defaults to 5432, database name to grist, and any sslmode other than disable turns on SSL.
S3Endpoint Yes string Full URL of the S3-compatible storage holding the Grist document files, e.g. https://minio.example.com or http://host:9000. Port defaults to 443 for https and 80 for http.
S3Bucket Yes string Name of an existing bucket for Grist documents. Versioning must be enabled on it.
S3AccessKey Yes string, sensitive Access key (user name) for the bucket. For OSC MinIO this is the RootUser.
S3SecretKey Yes string, sensitive Secret key (password) for the bucket. For OSC MinIO this is the RootPassword.
AdminEmail Yes string Email address of the Grist default user and installation admin, e.g. admin@example.com. Open /login once to sign in as this user.
SessionSecret No string, sensitive Random string used to sign login sessions. If left empty a new one is generated on each start, which signs everyone out when the instance restarts. Set it to keep sessions across restarts.

Sensitive options should be passed as {{secrets.NAME}}, which must be the entire field value.

PostgreSQL options (birme-osc-postgresql)

Option Required Type Meaning
name Yes string Instance name.
PostgresPassword Yes string, sensitive Password for the PostgreSQL superuser. Example: {{secrets.postgrespwd}}.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Default database created at start. Defaults to the same name as the user.
PostgresInitDbArgs No string Extra arguments passed to initdb (for example encoding or locale).
PostgresInitDbSql No string SQL run during database initialization.

MinIO options (minio-minio)

Option Required Type Meaning
name Yes string Instance name.
RootUser No string Admin user name; the S3 access key (AWS_ACCESS_KEY_ID) for clients. OSC can generate it.
RootPassword No string, sensitive Admin password; the S3 secret key (AWS_SECRET_ACCESS_KEY). Must match ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{10,}$ (at least 10 characters with lower case, upper case and a digit). OSC can generate it.

Resources