Service: Grist Core - EyevinnOSC/community GitHub Wiki
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.
- 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.
Create the dependencies first and confirm each is running before creating Grist:
-
PostgreSQL (
birme-osc-postgresql) for users, workspaces and document metadata. Read its address and port withdescribe-service-instance. The connection URL has the formpostgres://postgres:<password>@<IP>:<PORT>/grist. -
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 MinIORootUserand the secret key is theRootPassword. - Store credentials as service secrets with
create-service-secret(serviceIdgristlabs-grist-core), for examplegriststatedbfor the PostgreSQL URL andgrists3secretfor 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.
| 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.
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. |
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. |
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]"- The S3 bucket must have versioning enabled, otherwise Grist exits at startup.
- Without
SessionSecret, users are signed out whenever the instance restarts.