Service: Grist Core - EyevinnOSC/community GitHub Wiki

Grist Core

Grist Core (serviceId gristlabs-grist-core) is an open-source (Apache-2.0) relational spreadsheet: a familiar spreadsheet UI with database-style tables, typed columns and formulas that recalculate when data changes. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance that depends on a PostgreSQL database and S3-compatible object storage.

What it can do

  • Build relational tables with typed columns and Python formulas (including many Excel-style functions).
  • Build dashboards with linked widgets such as charts, cards, calendars and summary tables.
  • Import and export data (CSV, Excel, Google Drive, Airtable import).
  • Expose a REST API with an interactive API console, and webhooks.
  • Apply access rules down to rows, columns and tables; collaborate with comments and suggestions.
  • Store documents in a portable format based on SQLite.

Creating an instance

Create the dependencies first and confirm each is running before creating Grist:

  1. PostgreSQL (birme-osc-postgresql) for users, workspaces and document metadata. Read its address and port with describe-service-instance. The connection URL has the form postgres://postgres:<password>@<IP>:<PORT>/grist.
  2. MinIO (minio-minio) for the document files. Create a bucket for Grist and enable versioning on it; without versioning Grist stops at startup with a fatal error. The S3 access key is the MinIO RootUser and the secret key is the RootPassword.
  3. Store credentials as service secrets with create-service-secret (serviceId gristlabs-grist-core), for example griststatedb for the PostgreSQL URL and grists3secret for the MinIO secret key.

Then call create-service-instance with serviceId: "gristlabs-grist-core"; the instance name must be alphanumeric and at most 20 characters.

{
  "name": "mygrist",
  "DatabaseUrl": "{{secrets.griststatedb}}",
  "S3Endpoint": "https://<minio-host>",
  "S3Bucket": "grist",
  "S3AccessKey": "<minio-root-user>",
  "S3SecretKey": "{{secrets.grists3secret}}",
  "AdminEmail": "[email protected]"
}

Verify with wait-for-service-ready or get-instance-status, and use describe-service-instance for the URL.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
DatabaseUrl Yes string, sensitive PostgreSQL connection URL for Grist's home database, for example postgres://user:password@host:5432/grist. Only postgres:// or postgresql:// URLs work; the port defaults to 5432, the database name to grist, and any sslmode other than disable turns on SSL. Feeds DATABASE_URL.
S3Endpoint Yes string Full URL of the S3-compatible storage holding the Grist documents, such as https://minio.example.com or http://host:9000. The port defaults to 443 for https and 80 for http. Feeds S3_ENDPOINT.
S3Bucket Yes string Name of an existing bucket for Grist documents. Versioning must be enabled. Feeds S3_BUCKET.
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, for example [email protected]. Open /login once to sign in as this user. Feeds ADMIN_EMAIL.
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. Feeds GRIST_SESSION_SECRET.

DatabaseUrl, S3AccessKey, S3SecretKey and SessionSecret are sensitive: store them as service secrets and pass them as {{secrets.NAME}}, which only works as the entire field value. Overwriting a secret does not restart a running instance.

PostgreSQL options

Service birme-osc-postgresql (MIT), used as Grist's home database.

Option Required Type Meaning
name Yes string Name of the instance.
PostgresPassword Yes string, sensitive Password of the PostgreSQL superuser; use {{secrets.postgrespwd}}.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Name of the default database created at start. Defaults to the user name.
PostgresInitDbArgs No string Extra arguments passed to initdb, for example encoding or locale.
PostgresInitDbSql No string SQL executed during initialization for custom setup.

MinIO options

Service minio-minio (AGPL-3.0), used for Grist document storage.

Option Required Type Meaning
name Yes string Name of the instance.
RootUser No string Admin user name; the S3 access key (AWS_ACCESS_KEY_ID) when using an S3 client. Can be generated by the system.
RootPassword No string, sensitive Admin password; the S3 secret key (AWS_SECRET_ACCESS_KEY). At least 10 characters with a lowercase letter, an uppercase letter and a digit. Can be generated by the system.

Using the instance

Grist has no default password. Open /login on the instance URL once to sign in as the user whose address you set in AdminEmail.

osc create gristlabs-grist-core mygrist \
  -o DatabaseUrl="{{secrets.griststatedb}}" \
  -o S3Endpoint="https://example.minio.example.com" \
  -o S3Bucket="grist" \
  -o S3AccessKey="<access-key>" \
  -o S3SecretKey="{{secrets.grists3secret}}" \
  -o AdminEmail="[email protected]"

Limitations

  • The S3 bucket must have versioning enabled, otherwise Grist exits at startup.
  • Without SessionSecret, users are signed out whenever the instance restarts.

Resources

⚠️ **GitHub.com Fallback** ⚠️