snapshots: rewrite the various commands into a single Compose setup #477
Conversation
✅ Deploy Preview for grist-help-preview ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
jordigh
force-pushed
the
jordigh/snapshots
branch
from
952fbe8 to
fe3560d
Compare
|
Hmm this feels like the wrong direction for documentation? Setting up snapshots is currently hard, you have to know a bunch of stuff. The docker compose template could help if you are just trying to do some local testing, but then you'll need to actually understand all the bits and pieces when you go to do something real. I feel because there are more lines here, people are more likely to copy and paste than they are to understand something shorter that was never intended to actually be literally run. The ideal is an admin section that helps you get going step by step, and offers diagnostics. Like is there a bucket attached. Does it have versioning set up. etc. Linking to a docker compose example would be fine. I might well be wrong on this, so suggest soliciting a couple points of view. |
|
Btw some really good information to add in an update to the snapshot docs is "IF YOU HAVE VALUABLE DATA ALREADY, REALLY TRULY MAKE BACKUPS OF ALL YOUR DOCS BECAUSE YOU ARE VERY LIKELY TO LOSE THEM AT LEAST ONCE TRYING THIS." It can be a traumatic transition right now, like migrating to Postgres. |
|
I still want to push for a Compose file. The original instructions introduce some unnecessary complexity requiring to manually set up a Docker network, which Compose handles transparently, as well as being split over a series of commands, which to me also feels like individually each sets up an unnecessary point of possible failure. A collection of containers, even as an example, seems much more naturally suited for a Compose setup. I also see value in giving our users a test environment that immediately works. It inspires confidence and gives a good pattern on which to build a production version afterwards, whether with Compose, Podman, or k8s. I did label this file an example, with comments on what parts to remove or change for a more production version. I should probably clarify in the comments a bit more the details on setting up MinIO in a more realistic production version. Seeing some examples of how users actually self-host Grist, a Compose setup seems like a much more natural starting point. |
jordigh
force-pushed
the
jordigh/snapshots
branch
from
fe3560d to
b983ad4
Compare
I've added a warning to this effect. |
help/en/docs/self-managed.md
Outdated
| # | ||
| # ... | ||
| ports: | ||
| - 8484:8448 |
There was a problem hiding this comment.
Oops. I swear I actually ran this example before publishing it. Not sure how this happened. Fixed!
Running a series of Docker commands plus initialisation commands is a bit daunting. There are several steps to take, each of which could be subtly wrong. It seems very error-prone to me. This example condenses all of those steps into just two files and a single command to run: `docker compose up`. Hopefully this will be a better explanation and easier to follow.
jordigh
force-pushed
the
jordigh/snapshots
branch
from
b983ad4 to
28729a3
Compare
There was a problem hiding this comment.
I think this is an improvement over the original docs, but might benefit from a little more explanation before we leap into the example.
Something along these lines:
Grist's cloud storage is automatically enabled when Grist is configured with access to an external store. This is done by setting specific environment variables for the desired store (e.g. MinIO).
In addition to storage, connecting Grist to a Redis instance is beneficial to snapshot storage for .
The example compose file below demonstrates a minimum setup to use Grist with Minio as a snapshot store. It shows the environment variables that need to be set, and starts up an example Grist instance with corresponding MinIO and Redis services.
Additionally, it configures MinIO for snapshot storage. Crucially it:
- Creates a new bucket for Grist to use.
- Enables versioning on the bucket.
- Enables anonymous access.
Then proceed to the example. So we're explaining:
- The main settings Grist needs
- How MinIO needs to be set up.
As it's implicit in the example right now, but would be nice to be explicit up front :)
Edit: Reading Paul's comments, I think I'm agreeing with him? The most benefit I can see is from explaining the requirements / steps to a user, rather than handing over an example. Although I also don't see an issue with keeping / linking the compose file - I think it's clearer than the actual docker commands.
We could split the compose file up into each service, and explain it perhaps?
Running a series of Docker commands plus initialisation commands is a bit daunting. There are several steps to take, each of which could be subtly wrong. It seems very error-prone to me.
This example condenses all of those steps into just two files and a single command to run:
docker compose up. Hopefully this will be a better explanation and easier to follow.Thanks to @Spoffy for the initial Compose setup that I worked from.