Summary:
This updates the grist-core README to list specific features of Grist,
to make it easier for a casual visitor to get a sense of its scope. Adds links
to some new resources (reviews, templates, grist v airtable post) that could
also help. Adds python3 to docker image so that templates work without fuss.
Test Plan: existing tests should pass
Reviewers: georgegevoian
Reviewed By: georgegevoian
Subscribers: dsagal, anaisconce
Differential Revision: https://phab.getgrist.com/D3204
Grist is a modern relational spreadsheet. It combines the flexibility of a spreadsheet with the
robustness of a database to organize your data and make you more productive.
> :warning: This repository is in a pre-release state. Its release will be announced when it has
all the planned components, and a solid independent build and test set-up. Currently, stand-alone
server functionality is present, along with a single-user web client.
## Features
(By popular request: we have a specific write-up of [Grist vs Airtable](https://www.getgrist.com/blog/grist-v-airtable/) that may be helpful).
Grist is a hybrid database/spreadsheet, meaning that:
- Columns work like they do in databases. They are named, and hold one kind of data.
- Columns can be filled by formula, spreadsheet-style, with automatic updates when referenced cells change.
Here are some specific feature highlights of Grist:
* Python formulas.
- Full [Python syntax is supported](https://support.getgrist.com/formulas/#python), and the standard library.
- Many [Excel functions](https://support.getgrist.com/functions/) also available.
* A portable, self-contained format.
- Based on SQLite, the most widely deployed database engine.
- Any tool that can read SQLite can read numeric and text data from a Grist file.
- Great format for [backups](https://support.getgrist.com/exports/#backing-up-an-entire-document) that you can be confident you can restore in full.
- Great format for moving between different hosts.
* Convenient editing and formatting features.
- Choices and [choice lists](https://support.getgrist.com/col-types/#choice-list-columns), for adding colorful tags to records without fuss.
- [References](https://support.getgrist.com/col-refs/#creating-a-new-reference-list-column) and reference lists, for cross-referencing records in other tables.
- [Attachments](https://support.getgrist.com/col-types/#attachment-columns), to include media or document files in records.
- Dates and times, toggles, and special numerics such as currency all have specialized editors and formatting options.
* Great for dashboards, visualizations, and data entry.
- [Charts](https://support.getgrist.com/widget-chart/) for visualization.
- [Summary tables](https://support.getgrist.com/summary-tables/) for summing and counting across groups.
- [Widget linking](https://support.getgrist.com/linking-widgets/) streamlines filtering and editing data.
Grist has a unique approach to visualization, where you can lay out and link distinct widgets to show together,
without cramming mixed material into a table.
- The [Filter bar](https://support.getgrist.com/search-sort-filter/#filter-buttons) is great for quick slicing and dicing.
- So you can import a CSV of the last three months activity from your bank...
- ... and import new activity a month later without fuss or duplicates.
* Integrations.
- A [REST API](https://support.getgrist.com/api/), [Zapier actions/triggers](https://support.getgrist.com/integrators/#integrations-via-zapier), and support from similar [integrators](https://support.getgrist.com/integrators/).
- Import/export to Google drive, Excel format, CSV.
- Can link data with custom widgets hosted externally.
* [Many templates](https://templates.getgrist.com/) to get you started, from investment research to organizing treasure hunts.
* Access control options.
- (You'll need SSO logins set up to make use of these options)
- Share [individual documents](https://support.getgrist.com/sharing/), or workspaces, or [team sites](https://support.getgrist.com/team-sharing/).
- Control access to [individual rows, columns, and tables](https://support.getgrist.com/access-rules/).
- Control access based on cell values and user attributes.
* Can be self-maintained.
- Useful for intranet operation and specific compliance requirements.
This repository, [grist-core](https://github.com/gristlabs/grist-core), is maintained by Grist
Labs. Our flagship product, available at [getgrist.com](https://www.getgrist.com), is built from the code you see
here, combined with business-specific software designed to scale it to many users, handle billing,
etc.
If you are looking to use Grist in the cloud, head on over to [getgrist.com](https://www.getgrist.com).
If you are curious about where Grist is going heading,
see [our roadmap](https://github.com/gristlabs/grist-core/projects/1), drop a
question in [our forum](https://community.getgrist.com),
or browse [our extensive documentation](https://support.getgrist.com).
## Using Grist
## Opening and editing a Grist document locally
There are docker images set up for individual use, or (with some
configuration) for self-hosting. Grist Labs offers a hosted service
at [https://docs.getgrist.com](docs.getgrist.com).
The easiest way to use Grist locally on your computer is with [Docker](https://www.docker.com/get-started).
From a terminal, do:
To run Grist running on your computer with [Docker](https://www.docker.com/get-started), do:
```sh
docker pull gristlabs/grist
docker run -p 8484:8484 -it gristlabs/grist
```
Then visit `http://localhost:8484` in your browser. You'll be able to create and edit documents,
and to import documents downloaded from the https://docs.getgrist.com host. You'll also be able
to use the Grist API.
To preserve your work across docker runs, provide a directory to save it in:
Then visit `http://localhost:8484` in your browser. You'll be able to create, edit, import,
and export documents. To preserve your work across docker runs, share a directory as `/persist`:
```sh
docker pull gristlabs/grist
docker run -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist
```
## Building from source
Get templates at https://templates.getgrist.com/ for payroll,
inventory management, invoicing, D&D encounter tracking, and a lot
more, or use any document you've created on
[https://docs.getgrist.com](docs.getgrist.com).
Here are the steps needed:
If you need to change the port Grist runs on, set a `PORT` variable, don't just change the
port mapping:
```sh
yarn install
yarn run build:prod
yarn run install:python
yarn start
# grist client available at http://localhost:8484
# grist api available at http://localhost:8484/api/
```
docker run --env PORT=9999 -p 9999:9999 -v $PWD/persist:/persist -it gristlabs/grist
```
## Building from source
To build Grist from source, follow these steps:
Then you can use the Grist client, or the API. You can view and edit Grist documents
throught the client and the API. All imported/created documents will appear in the `docs`
subdirectory. You cannot (yet) edit Grist documents in place on your file system.
yarn install
yarn run build:prod
yarn run install:python
yarn start
# Grist will be available at http://localhost:8484/
Grist does not have a login system built in. To activate one, you can configure Grist
to talk to an identity provider such as Auth0 using
## Logins
Like git, Grist has features to track document revision history. So for full operation,
Grist expects to know who the user modifying a document is. Until it does, it operates
in a limited anonymous mode. To get you going, the docker image is configured so that
when you click on the "sign in" button Grist will attribute your work to `you@example.com`.
Change this by setting `GRIST_DEFAULT_EMAIL`:
```
docker run --env GRIST_DEFAULT_EMAIL=my@email -p 8484:8484 -v $PWD/persist:/persist -it gristlabs/grist
```
You can change your name in `Profile Settings` in
the [User Menu](https://support.getgrist.com/glossary/#user-menu).
For multi-user operation, and/or if you wish to access Grist across the
public internet, you'll want to connect it to your own single sign-in service