Grist Omnibus (DEPRECATED)

⚠️ This project is deprecated and no longer being developed.

Grist Omnibus existed to make it easy to spin up Grist on a server with logins working right away. Regular Grist now does that job better, so there is no longer a good reason to use the omnibus:

1. Sign in with getgrist.com - a self-hosted Grist can let you and your colleagues log in using getgrist.com accounts, with no identity provider to configure.
2. Quick setup - Grist has a first-run setup wizard that walks you through the basics in the browser, instead of a pile of environment variables.
3. Active maintenance - the regular gristlabs/grist image gets constant attention (new features, security fixes, dependency updates). This project does not.

What to use instead:

• The regular Grist Docker image, gristlabs/grist. Start with the self-managed Grist guide, then use quick setup and sign in with getgrist.com.
• If you want a bundled, supported install with your own identity provider, see the marketplace offerings for AWS and Azure.
• For SSO with your own OIDC or SAML provider, see the OIDC and SAML docs for Grist itself.

If you are already using the omnibus: the images continue to exist, and your /persist directory holds an ordinary Grist installation (/persist/docs, /persist/home.sqlite3) in the same layout the regular gristlabs/grist image uses (gristlabs/grist-ee if you were using grist-ee-omnibus). To migrate:

1. Decide on and configure authentication using one of the options above before starting the regular image on the old data. Grist without authentication treats every visitor as the default user. Accounts are matched by email address, so the new login method must give your users the same email addresses they had with the omnibus, or they will not see their documents.
2. Run the regular image with the same /persist volume, and carry over the settings the omnibus applied for you: GRIST_SINGLE_ORG (your TEAM), GRIST_DEFAULT_EMAIL (your EMAIL), GRIST_ORG_IN_PATH=false, GRIST_FORCE_LOGIN=true, GRIST_SANDBOX_FLAVOR=gvisor, and GRIST_SESSION_SECRET=$(cat /persist/params/GRIST_SESSION_SECRET) (unless you had set your own).
3. Once everything works, delete the omnibus-only entries in /persist: auth, params, acme.json and dex-full.yaml. They contain password hashes, session secrets and tokens that the regular image does not use.

No further development of the omnibus should be expected.

The original documentation follows for reference only. Please do not start new installations with the omnibus.

This was an experimental way to install Grist on a server quickly with authentication and certificate handling set up out of the box.

So you and your colleagues can log in:

And use Grist without fuss:

It bundles:

• Grist itself from grist-core - Grist is a handy spreadsheet / online database app, presumably you like it and that's why you are here.
• A reverse proxy, Traefik - we use this to coordinate with Let's Encrypt to get a certificate for https traffic.
• An identity service, Dex - this can connect to LDAP servers, SAML providers, Google, Microsoft, etc, and also (somewhat reluctantly) supports hard-coded user/passwords that can be handy for a quick fuss-free test.

Here's the minimal configuration you need to provide.

• EMAIL: an email address, used for Let's Encrypt and for initial login.
• PASSWORD: optional - if you set this, you'll be able to log in without configuring any other authentication settings. You can add more accounts as EMAIL2, PASSWORD2, EMAIL3, PASSWORD3 etc.
• TEAM - a short lowercase identifier, such as a company or project name (grist-labs, cool-beans). Just a-z, 0-9 and - characters please.
• URL - this is important, you need to provide the base URL at which Grist will be accessed. It could be something like https://grist.example.com, or http://localhost:9999. No path element please.
• HTTPS - mandatory if URL is https protocol. Can be auto (Let's Encrypt) if Grist is publically accessible and you're cool with automatically getting a certificate from Let's Encrypt. Otherwise use external if you are dealing with ssl termination yourself after all, or manual if you want to provide a certificate you've prepared yourself (there's an example below).

The minimal storage needed is an empty directory mounted at /persist.

So here is a complete docker invocation that would work on a public instance with ports 80 and 443 available:

mkdir -p /tmp/grist-test
docker run \
  -p 80:80 -p 443:443 \
  -e URL=https://cool-beans.example.com \
  -e HTTPS=auto \
  -e TEAM=cool-beans \
  -e EMAIL=owner@example.com \
  -e PASSWORD=topsecret \
  -v /tmp/grist-test:/persist \
  --name grist --rm \
  -it gristlabs/grist-omnibus  # or grist-ee-omnibus for enterprise

And here is an invocation on localhost port 9999 - the only differences are the -p port configuration and the -e URL= environment variable.

mkdir -p /tmp/grist-test
docker run \
  -p 9999:80 \
  -e URL=http://localhost:9999 \
  -e TEAM=cool-beans \
  -e EMAIL=owner@example.com \
  -e PASSWORD=topsecret \
  -v /tmp/grist-test:/persist \
  --name grist --rm \
  -it gristlabs/grist-omnibus  # or grist-ee-omnibus for enterprise

If providing your own certificate (HTTPS=manual), provide a private key and certificate file as /custom/grist.key and custom/grist.crt respectively:

docker run \
  ...
  -e HTTPS=manual \
  -v $(PWD)/key.pem:/custom/grist.key \
  -v $(PWD)/cert.pem:/custom/grist.crt \
  ...

Remember if you are on a public server you don't need to do this, you can set HTTPS=auto and have Traefik + Let's Encrypt do the work for you.

If you run the omnibus behind a separate reverse proxy that terminates SSL, then you should HTTPS=external, and set an additional environment variable TRUSTED_PROXY_IPS to the IP address or IP range of the proxy. This may be a comma-separated list, e.g. 127.0.0.1/32,192.168.1.7. See Traefik's forwarded headers.

You can change dex.yaml (for example, to fill in keys for Google and Microsoft sign-ins, or to remove them) and then either rebuild the image or (easier) make the custom settings available to the omnibus as /custom/dex.yaml:

docker run \
  ...
  -v $PWD/dex.yaml:/custom/dex.yaml \
  ...

You can tell it is being used because Using /custom/dex.yaml will be printed instead of No /custom/dex.yaml.