Getting Started

Grist is an open source relational spreadsheet. It combines the flexibility of a spreadsheet with the robustness of a database, with linked tables, formulas in Python and custom views. Available as an open web service in Eyevinn Open Source Cloud. This tutorial walks you through the steps to get started.

Prerequisites

Grist on OSC needs two dependencies: a PostgreSQL database for users, workspaces and document metadata, and an S3-compatible bucket (for example OSC MinIO) for the document files.

Step 1: Create a PostgreSQL database

Navigate to the PostgreSQL service and create an instance. Note the connection URL, which has the form postgres://user:password@host:port/grist. Only postgres:// and postgresql:// URLs are supported. The port defaults to 5432 and the database name to grist if omitted.

Step 2: Create a MinIO bucket with versioning

Create a MinIO instance (see Service: MinIO) and create a bucket for Grist documents. Versioning must be enabled on the bucket, 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.

Step 3: Store credentials as secrets

Go to the Grist service page, open the tab "Service Secrets" and create secrets for the sensitive values:

  • griststdb: the PostgreSQL connection URL
  • grists3access: the S3 access key
  • grists3secret: the S3 secret key

Step 4: Create the Grist instance

Go to the tab "Grist cores" and click "Create grist-core". Fill in:

Field Description
Name Instance name, alphanumeric only
DatabaseUrl {{secrets.griststdb}}
S3Endpoint Full URL of the S3 storage, for example https://<tenant>-guide.minio-minio.auto.prod.osaas.io
S3Bucket Name of the versioned bucket
S3AccessKey {{secrets.grists3access}}
S3SecretKey {{secrets.grists3secret}}
AdminEmail Email of the default user and installation admin
SessionSecret Optional random string used to sign login sessions

Set SessionSecret if you do not want everyone to be signed out when the instance restarts. If it is left empty a new secret is generated on each start.

Step 5: Log in

Click on the instance card when the status is green and "running". Open /login once on your instance URL to sign in as the user you set in AdminEmail. That user is the default user and the installation admin. There is no default password: the service has no built-in username and password pair.

CLI usage

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

Resources