Service: Grist - EyevinnOSC/community GitHub Wiki
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.
- 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.
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. Onlypostgres://andpostgresql://are supported; port defaults to 5432 and database name togrist. - 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 theRootUserand the secret key is theRootPassword.
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": "[email protected]"
}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="[email protected]"| 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. [email protected]. 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.
| 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. |
| 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. |