Grist Omnibus

This is an experimental way to install Grist on a server quickly with authentication and certificate handling set up out of the box. Grist Labs also has marketplace offerings for AWS and Azure.

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.
• An authentication middleware, traefik-forward-auth to connect Grist and Dex via Traefik.

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.