Adds docker compose examples (#1113)

This adds three example docker-compose files:

- A basic Grist instance backed by sqlite, with no additional services.
- A Grist instance that uses Postgres, Redis and MinIO.
- A Grist instance that uses OIDC authentication and traefik.

These are intended to be customised by self-hosters for their own needs.

All examples should work without any additional configuration.

.gitignore

@@ -83,3 +83,8 @@ xunit.xml
 
 # ext directory can be overwritten
 ext/**
+
+# Docker compose examples - persistent values and secrets
+/docker-compose-examples/*/persist
+/docker-compose-examples/*/secrets
+/docker-compose-examples/grist-traefik-oidc-auth/.env

docker-compose-examples/grist-local-testing/README.md

@@ -0,0 +1,12 @@
+This is the simplest example that runs Grist, suitable for local testing.
+
+It is STRONGLY RECOMMENDED not to use this container in a way that makes it accessible to the internet.
+This setup lacks basic security or authentication.
+
+Other examples demonstrate how to set up authentication and HTTPS.
+
+See https://support.getgrist.com/self-managed for more information.
+
+## How to run this example
+
+This example can be run with `docker compose up`.

docker-compose-examples/grist-local-testing/docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  grist:
+    image: gristlabs/grist:latest
+    volumes:
+      # Where to store persistent data, such as documents.
+      - ${PERSIST_DIR}/grist:/persist
+    ports:
+      - 8484:8484

docker-compose-examples/grist-traefik-basic-auth/README.md

@@ -0,0 +1,24 @@
+This is the simplest example of Grist with authentication and HTTPS encryption.
+
+It uses Traefik as:
+- A reverse proxy to manage certificates and provide HTTPS support
+- A basic authentication provided using Traefik's Basic Auth middleware.
+
+This setup, after configuring HTTPS certificates correctly, should be acceptable on the public internet.
+
+However, it doesn't allow a user to sign-out due to the way browsers handle basic authentication.
+
+You may want to try a more secure authentication setup such Authelia, Authentik or traefik-forward-auth.
+The OIDC auth example demonstrates a setup using Authelia.
+
+See https://support.getgrist.com/self-managed for more information.
+
+## How to run this example
+
+This example can be run with `docker compose up`.
+
+The default login is:
+- Username: `[email protected]`
+- Password: `test`
+
+This can be changed in `./configs/traefik-dynamic-config.yaml`. Instructions on how to do this are available in that file.

docker-compose-examples/grist-traefik-basic-auth/configs/traefik-config.yml

@@ -0,0 +1,35 @@
+providers:
+  # Enables reading docker label config values
+  docker: {}
+  # Read additional config from this file.
+  file:
+    directory: "/etc/traefik/dynamic"
+
+entrypoints:
+  # Defines a secure entrypoint using TLS encryption
+  websecure:
+    address: ":443"
+    http:
+      tls: true
+  # Defines an insecure entrypoint that redirects to the secure one.
+  web:
+    address: ":80"
+    http:
+      # Redirects HTTP to HTTPS
+      redirections:
+        entrypoint:
+          to: "websecure"
+          scheme: "https"
+
+# Enables automatic certificate renewal
+certificatesResolvers:
+  letsencrypt:
+    acme:
+      email: "[email protected]"
+      storage: /acme/acme.json
+      tlschallenge: true
+
+# Enables the web UI
+# This is disabled by default for security, but can be useful to debugging traefik.
+api:
+  # insecure: true

docker-compose-examples/grist-traefik-basic-auth/configs/traefik-dynamic-config.yml

@@ -0,0 +1,13 @@
+http:
+  # Declaring the user list
+  middlewares:
+    grist-basic-auth:
+      basicAuth:
+        # The header that Grist will listen for authenticated usernames on.
+        headerField: "X-Forwarded-User"
+        # This is the list of users, in the format username:password.
+        # Passwords can be created using `htpasswd`
+        # E.g: `htpasswd -nB [email protected]`
+        users:
+          # The default username is "[email protected]". The default password is "test".
+          - "[email protected]:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"

docker-compose-examples/grist-traefik-basic-auth/docker-compose.yml

@@ -0,0 +1,44 @@
+services:
+  grist:
+    image: gristlabs/grist:latest
+    environment:
+      # Sets the header to look at for authentication
+      GRIST_FORWARD_AUTH_HEADER: X-Forwarded-User
+      # Forces Grist to only use a single team called 'Example'
+      GRIST_SINGLE_ORG: my-grist-team   # alternatively, GRIST_ORG_IN_PATH: "true" for multi-team operation
+      # Force users to login (disable anonymous access)
+      GRIST_FORCE_LOGIN: true
+      # Base URL Grist redirects to when navigating. Change this to your domain.
+      APP_HOME_URL: https://grist.localhost
+      # Default email for the "Admin" account
+      GRIST_DEFAULT_EMAIL: [email protected]
+    volumes:
+      # Where to store persistent data, such as documents.
+      - ${PERSIST_DIR}/grist:/persist
+    labels:
+      - "traefik.http.services.grist.loadbalancer.server.port=8484"
+      - "traefik.http.routers.grist.rule=Host(`grist.localhost`)"
+      - "traefik.http.routers.grist.tls.certresolver=letsencrypt"
+      - "traefik.http.routers.grist-auth.rule=Host(`grist.localhost`) && (PathPrefix(`/auth/login`) || PathPrefix(`/_oauth`))"
+      - "traefik.http.routers.grist-auth.middlewares=grist-basic-auth@file"
+      - "traefik.http.routers.grist-auth.tls.certresolver=letsencrypt"
+
+  traefik:
+    image: traefik:latest
+    ports:
+      # HTTP Ports
+      - "80:80"
+      - "443:443"
+      # The Web UI (enabled by --api.insecure=true)
+      # - "8080:8080"
+    volumes:
+      # Set the config file for traefik - this is loaded automatically.
+      - ./configs/traefik-config.yml:/etc/traefik/traefik.yml
+      # Set the config file for the dynamic config, such as middleware.
+      - ./configs/traefik-dynamic-config.yml:/etc/traefik/dynamic/dynamic-config.yml
+      # Certificate location, if automatic certificate setup is enabled.
+      - ./configs/acme:/acme
+      # Traefik needs docker access when configured via docker labels.
+      - /var/run/docker.sock:/var/run/docker.sock
+    depends_on:
+      - grist

docker-compose-examples/grist-traefik-oidc-auth/README.md

@@ -0,0 +1,32 @@
+This is an example of Grist with Authelia for OIDC authentication, and Traefik for HTTP encryption and routing.
+
+OIDC enables authentication using many existing providers, including Google, Microsoft, Amazon and Okta.
+
+This example uses Authelia, which is a locally hosted OIDC provider, so that it can work without further setup. 
+However, Authelia could be easily replaced by one of the providers listed above, or other self-hosted alternatives,
+such as Authentik or Dex.
+
+This example could be hosted on a dedicated server, with the following changes:
+- DNS setup
+- HTTPS / Certificate setup (e.g Let's encrypt)
+
+See https://support.getgrist.com/install/oidc for more information on using Grist with OIDC.
+
+## How to run this example
+
+To run this example, you'll first need to generate several secrets needed by Authelia.
+
+This is automated for you in `generateSecureSecrets.sh`, which uses Authelia's docker image to populate the `./secrets` directory.
+
+This example can then be run with `docker compose up`. This will make Grist available on `https://grist.localhost` with a self-signed certificate (by default), after all the services have started. Note: it may take up to a minute for all of the services to start correctly.
+
+The self-signed certificate will cause a security warning in the web browser when you try to visit Grist.
+This is fine for local testing and can be bypassed, but correct certificates should be set up if Grist is being made
+available on the internet.
+
+### Users
+
+The default username is `test`, with password `test`.
+
+You can add or modify users in ./configs/authelia/user-database.yml. Additional instructions are provided in that file.
+