README.md

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.

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 protected] \
  -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 protected] \
  -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.