Feedback on the Query Sharing user manual
Closed this issue · 9 comments
While testing the feature here are the things I noticed can be improved in the Query Sharing user manual:
- User manual should start with the instructions on how to use the feature. Although we would love users to first understand everything under the hood, they still expect to first try out the feature. ("How to set it up" section should come first")
- There should be a clear distinction between Memgraph Enterprise license and Lab Enterprise license made -> you can't have multi-tenant setup without providing Memgraph Enterprise license to Memgraph and you can't have Query Sharing at all without providing Memgraph Enterprise license to Lab -> it's two different flows for users - database vs client setup.
- I would like to have additional information on the default values and cases when they're required for the Lab environment variables. Also, link to docs on how to set env vars in Lab Docker. Users can get frustrated if we just tell them to ensure that env vars are set correctly without additional info on how to do that.
- I would create two user flows under "How to set it up" section -> one with a separate Memgraph instance (this instance doesn't need to have Enterprise license if I understood correctly, but Lab needs it) and another with a NEW database defined in multi-tenant env (Memgraph and Lab have Enterprise licence) + this db name needs to be provided in STORAGE_MG_DATABASE_NAME.
Hi Kate, thanks for the feedback!
- Seems completely reasonable, we should switch these
- Far as I understand/remember (but can't really check implementation, @MarioHerceg might you back me up on this) - currently the licenses are one and the same. MVP approach, we haven't implemented a separate license for Lab.
- To see if I understand. Instead of this, something like this:
# host.docker.internal = check docs why you need to input this if
# you are running Docker on Mac/Windows
STORAGE_MG_HOST=host.docker.internal
STORAGE_MG_PORT=7688
# Default is false, so you need to define it only if it is true
STORAGE_MG_IS_ENCRYPTED=false
#If you are using multitenancy, you need to input a database name
# here
STORAGE_MG_DATABASE_NAME=string
# If you created a user in the remote storage Memgraph, make sure to
# create a username and password that the Lab will use, otherwise, don't
# even bother defining these
STORAGE_MG_USERNAME=string
STORAGE_MG_PASSWORD=string
?
OR
just add another column to the table with default values?
- Not sure I can cover this atm. Dunno if @kgolubic or @MarioHerceg might pitch in so it doesn't wait for Toni. He wouldn't be mad, just disappointed 😂 (I'm kidding)
Btw, the source of the codeblock included in the comment obviously did not come out of my superior knowledge about how to set this up, but from Toni's notes.
I can't remember exactly for Lab vs Enterprise licence, but I will try to find out today
- Yes, based on what I can see, we are currently using memgraph license in Lab, but in the future Lab will have its own license
- You can do here however you think it is the best. There is a sentence in How to set it up that says
Ensure that this Memgraph instance or Memgraph database (in a multi-tenant environment) is used exclusively by the Lab to avoid data corruption and an inconsistent state.. If you think that is not enough, feel free to expand it.
We are using the same enterprise license, but if I understood it correctly, you have to set it both for Lab and for Memgraph in a different way with different commands.
Yes, the license should be setup in Lab, you're right, I was just not sure because of the way we phrased it that we're on the same page.
Thanks @katarinasupe for the feedback!
"How to set it up" section should come first"
This totally makes sense.
There should be a clear distinction between Memgraph Enterprise license and Lab Enterprise license made -> you can't have multi-tenant setup without providing Memgraph Enterprise license to Memgraph and you can't have Query Sharing at all without providing Memgraph Enterprise license to Lab -> it's two different flows for users - database vs client setup.
Is this what you actually wrote in the last paragraph: "I would create two user flows under "How to set it up" section -> one with a separate Memgraph instance (this instance doesn't need to have Enterprise license if I understood correctly, but Lab needs it) and another with a NEW database defined in multi-tenant env (Memgraph and Lab have Enterprise licence) + this db name needs to be provided in STORAGE_MG_DATABASE_NAME."
If yes, then this makes sense too. Lab uses Memgraph enterprise licence and actually there are 3 cases:
- Lab with licence, Memgraph without license but used only by the Lab
- Lab with license, Memgraph with license without multi-tenancy (this still works)
- Lab with license, Memgraph with license with multi-tenancy
Do you think we need to cover all three, or just two: MG with/without licence?
I would like to have additional information on the default values and cases when they're required for the Lab environment variables. Also, link to docs on how to set env vars in Lab Docker. Users can get frustrated if we just tell them to ensure that env vars are set correctly without additional info on how to do that.
We have defaults here: https://memgraph.com/docs/data-visualization/install-and-connect#environment-variables - is this what you meant? Would just a link to this page for default env variables be enough? This document also has information on how to set up env variables in Docker.
Is this what you actually wrote in the last paragraph: "I would create two user flows under "How to set it up" section -> one with a separate Memgraph instance (this instance doesn't need to have Enterprise license if I understood correctly, but Lab needs it) and another with a NEW database defined in multi-tenant env (Memgraph and Lab have Enterprise licence) + this db name needs to be provided in STORAGE_MG_DATABASE_NAME."
Yes 😄
Do you think we need to cover all three, or just two: MG with/without licence?
I think just two. In my opinion, it's enough to explain minimal setup for all to work. In my head -> Lab requires license in any case - this is a prerequisite (how to set it up?). Then, in order for query sharing feature to work, you need separate Memgraph instance or Memgraph in multi-tenant env. Having a separate Memgraph instance can work with or without license, so I wouldn't mention license here at all (if the user has it, great, if they don't, it still works). For multi-tenant env, I would add how to set up that Memgraph (license + storage db name).
We have defaults here: https://memgraph.com/docs/data-visualization/install-and-connect#environment-variables - is this what you meant? Would just a link to this page for default env variables be enough? This document also has information on how to set up env variables in Docker.
I don't see the default values there for the envs related to query sharing? Are there any?
I am primarily asking because of the storage db name so the user understands how to correctly set it up in the multi-tenant env. I am also asking because I think user would want to understand are all envs required or not for feature to work. I agree with you that the link to the above is good enough for user to know how to set it up. Also, by improving the above flows, I think this won't be an issue anymore.
Great! All clear, I will add those changes to the "How it works"!
I don't see the default values there for the envs related to query sharing? Are there any?
Ah yes, there are no default values because we don't know by default where remote storage is :D As it is an enterprise feature it can be turned on/off, so having empty values indicates "not using the feature". I will add more info about this too because all env variables except STORAGE_HOST and STORAGE_PORT are actually optional to define. Now I am even seeing that it doesn't say which ones are required to define, and which are optional. Good catch!