Running Grist on your own computer is pretty easy. Hosting it to share with others requires a few more steps, such as hooking up an authentication method, wrangling certificates, and configuring a reverse proxy. I wanted to show one complete recipe for doing so.
Here is a docker-compose.yml file that does the following:
Uses the letsencrypt service to get a certificate for your domain.
Connects Grist to authentication middleware called traefik-forward-auth. You can configure this middleware to perform Google/OpenID oauth based login.
version: '3'
services:
reverse-proxy:
# Use Traefik for routing and certificate handling.
image: traefik:v2.6
command:
- --providers.docker
- --certificatesResolvers.letsencrypt.acme.email=${EMAIL}
- --certificatesResolvers.letsencrypt.acme.storage=/acme/acme.json
- --certificatesResolvers.letsencrypt.acme.tlschallenge=true
- --entrypoints.websecure.address=:443
- --entrypoints.websecure.http.tls=true
- --entrypoints.web.address=:80
- --entrypoints.web.http.redirections.entrypoint.to=websecure
- --entrypoints.web.http.redirections.entrypoint.scheme=https
ports:
- "80:80"
- "443:443"
volumes:
# You may want to put state somewhere other than /tmp :-)
- /tmp/grist/acme:/acme
# Traefik needs docker access when configured via docker labels.
- /var/run/docker.sock:/var/run/docker.sock
traefik-forward-auth:
# Authentication middleware.
# See https://github.com/thomseddon/traefik-forward-auth for
# options for configuring it.
image: thomseddon/traefik-forward-auth:2
environment:
PROVIDERS_GOOGLE_CLIENT_ID: your-google-client-id
PROVIDERS_GOOGLE_CLIENT_SECRET: your-google-client-secret
SECRET: something-random
LOGOUT_REDIRECT: "https://${DOMAIN}/signed-out"
labels:
traefik.http.services.traefik-forward-auth.loadbalancer.server.port: 4181
traefik.http.middlewares.traefik-forward-auth.forwardauth.address: "http://traefik-forward-auth:4181"
traefik.http.middlewares.traefik-forward-auth.forwardauth.authResponseHeaders: "X-Forwarded-User"
traefik.http.middlewares.no-forward-user-header.headers.customRequestHeaders.X-Forwarded-User: ""
grist:
image: gristlabs/grist
environment:
GRIST_FORWARD_AUTH_HEADER: X-Forwarded-User
GRIST_FORWARD_AUTH_LOGOUT_PATH: _oauth/logout
GRIST_SINGLE_ORG: grist # alternatively, GRIST_ORG_IN_PATH: "true" for multi-team operation
GRIST_DEFAULT_EMAIL: ${EMAIL}
APP_HOME_URL: https://${DOMAIN}
ports:
- "8484:8484"
volumes:
# You may want to put state somewhere other than /tmp :-)
- /tmp/grist/data:/persist
labels:
traefik.http.services.grist.loadbalancer.server.port: 8484
# When logging in and for tfa's own endpoints, use traefik-forward-auth middleware.
traefik.http.routers.login.rule: Host(`${DOMAIN}`) && (PathPrefix(`/auth/login`) || PathPrefix(`/_oauth`))
traefik.http.routers.login.middlewares: traefik-forward-auth
traefik.http.routers.login.service: grist
# Comment out each line with "letsencypt" in it if your domain is not publically
# accessible and you want to use a self-signed certificate.
traefik.http.routers.login.tls.certresolver: letsencrypt
# Otherwise, the middleware is not needed and would prevent
# public shares. Grist will redirect to login when needed.
traefik.http.routers.general.rule: Host(`${DOMAIN}`)
traefik.http.routers.general.middlewares: no-forward-user-header
traefik.http.routers.general.service: grist
traefik.http.routers.general.tls.certresolver: letsencrypt
The template expects you to set DOMAIN and EMAIL environment variables. The email you set will be used when auto-applying for a certificate, and will also be configured as the initial site owner. If using Google logins, you’ll need to set PROVIDERS_GOOGLE_CLIENT_ID and PROVIDERS_GOOGLE_CLIENT_SECRET with your own values, see provider setup documentation.
Once you are satisfied, you can just run docker-compose up to bring up the containers, and Grist should become available at your domain.
Other tweaks you can do when it is working:
Change where you want to store data in the volumes sections (probably not /tmp like in this template!).
Turn on sandboxing by adding GRIST_SANDBOX_FLAVOR=gvisor in the environment section for Grist if you plan on working with untrusted documents.
A lot more authentication options are possible by using Grist’s support for SAML via Authentik, Keycloak, Auth0 etc. There are some notes for Authentik at Grist core multi user docker setup. There is more flexibilty but more opportunities for misconfiguration than this (relatively) short traefik-based template.
thank you. I want to use this configuration, but with Caddy server and Authelia for authentication. Caddy supports forward_auth since Friday by default.
Where is /auth/login called in Grist? “Sign in” calls /signin?next=%2F on my Grist installation.
When there is no Sign in called for now because I open /, an empty Remote-Email header will be send to Grist. Grist then use GRIST_DEFAULT_EMAIL or you@example.com. How to avoid this? Trying GRIST_SUPPORT_ANON false or true doesn’t help.
Configuring authentication for the whole site /* works as expected, but as you wrote public sharing can’t work.
Can you double check that GRIST_FORWARD_AUTH_HEADER is set, and also optionally GRIST_FORWARD_AUTH_LOGOUT_PATH? If you get it working, I’d be happy to hear about what worked for you.
If I enable /auth/login only for authentication, pressing sign-in, Grist login with you@example.com and don’t see any /auth/login call.
Thank you and best regards,
Helmut
Edit: Oh no!!! Now I found the problem after looking to your text and my env file. Have always used GRIST_PROXY_AUTH_HEADER, but it’s GRIST_FORWARD_AUTH_HEADER. Now it’s working.
I think I lost 3h of my life last weekend and I think I’m using PROXY because of this thread:
Thank’s for replying. I think I never noted the difference, because the word PROXY makes also sense.
thanks a lot, it’s working well
Except for the : Examples & Templates
I have this msg : error: “organization not found”
Should it work ?
And is it normal that when I invite a person(gmail account) with it, no email is sent?
The examples & templates link isn’t configured well in self-hosted Grist, we should probably just hide it or have it link to https://templates.getgrist.com/
One thing to clarify. Regarding SSO. Let’s say you have three apps. All of them use auth on the reverse proxy: grist .example.com, whoami .example.com and whoami2 .example.com. On all of them the reverse proxy catch any /sign-out or /logout call and logout the session.
Following happens:
login with user1 on whoami .example.com. result: logged in with user1
open in another tab grist .example.com. result: need to press sign-in, no need to auth and also being logged in with user1
open in another tab whoami2 .example.com. result: logged in with user1
logout on whoami .example.com/logout. result: logged out, forced to login again with Authelia
switch to the tab with whoami2 .example.com, reload the page. result: because I’m still logged out, there is also Authelia’s login screen
For now it’s ok. Maybe grist should recognize the email header and don’t need to press sign-in first. But then something strange happens:
switch to the tab with grist, reload the page. result: still logged in on grist with user1!
It becomes even more strange:
still logged out. now login with user2 on whoami. result: logged in with user2
switch to the tab with whoami2, reload the page. result: logged in with user2
switch to the tab with grist, reload the page. result: still shows user1 logged in and it’s possible to open documents from user1!
Could this be an error in grist? At least with caddy’s forward_auth implementation, only the /auth/login call send the email header to grist. I think this should be the same with your traefik configuration?
We are using a traefik + docker setup thanks to your template. I’ve a question about keeping our instance up to date.
The grist-core release policy is not clear to me (I don’t see releases in github), and neither the releases in the Docker hub. What would you recommend for keeping a self-hosted version up to date ? Thanks!
Hi @Yohan_Boniface, the gristlabs/grist:latest image is generally updated around 6am UTC with the most recent version of grist-core that is passing all tests. At the time of writing, it last updated 2 days ago due to timeouts in the github action that updates it: Actions · gristlabs/grist-core · GitHub. This image is a good one to track to get the latest and greatest version of Grist, although there is some risk of untested behavior breaking.
So then there is no versioning scheme around at this time ? (I understand that Docker image is single-tagged “latest” and it runs main git branch ?)
We occasionally tag a version, but haven’t become systematic about it yet. gristlabs/grist:0.7.9 is the most recent tagged version, from some months ago (see Releases · gristlabs/grist-core · GitHub). We’ve talked about tagging on roughly a monthly basis. What would be your ideal?
Either YYYY.MM(-patch) in order to have a regular release (also better for communication), or YYYY.MM.DD(-patch) to make it more flexible and to release when it’s hot and the baker is awake!
Also, I’d say that having an easy way to know the running Grist version from within the client would very handy to help debugging bugs coming from Mars.
,