Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gristlabs/grist-omnibus
an opinionated Grist+Dex+Traefik package for first-time self-hosters
https://github.com/gristlabs/grist-omnibus
Last synced: 7 days ago
JSON representation
an opinionated Grist+Dex+Traefik package for first-time self-hosters
- Host: GitHub
- URL: https://github.com/gristlabs/grist-omnibus
- Owner: gristlabs
- License: apache-2.0
- Created: 2022-08-17T20:26:15.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-22T16:37:01.000Z (30 days ago)
- Last Synced: 2025-02-14T03:41:24.003Z (7 days ago)
- Language: JavaScript
- Size: 56.6 KB
- Stars: 67
- Watchers: 6
- Forks: 15
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://support.getgrist.com/install/grist-builder-edition/)
for [AWS](https://support.getgrist.com/install/grist-builder-edition/#aws) and [Azure](https://support.getgrist.com/install/grist-builder-edition/#azure).
So you and your colleagues can log in:
And use Grist without fuss:
It bundles:
* Grist itself from [grist-core](https://github.com/gristlabs/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](https://github.com/traefik/traefik) -
we use this to coordinate with Let's Encrypt to get a
certificate for https traffic.
* An identity service, [Dex](https://github.com/dexidp/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](https://github.com/thomseddon/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](https://doc.traefik.io/traefik/routing/entrypoints/#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`.