search

memgraph / documentation

The official documentation for Memgraph open-source graph database.
https://memgraph.com/docs
MIT License
10 stars 10 forks source link

Feedback on the Query Sharing user manual #889

Closed katarinasupe closed 4 months ago

katarinasupe commented 5 months ago

While testing the feature here are the things I noticed can be improved in the Query Sharing user manual:

Ana-Marija-design commented 5 months ago

Hi Kate, thanks for the feedback!

  1. Seems completely reasonable, we should switch these
  2. 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.
  3. 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? 

4. 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)
Ana-Marija-design commented 5 months ago

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.

MarioHerceg commented 5 months ago

I can't remember exactly for Lab vs Enterprise licence, but I will try to find out today

MarioHerceg commented 5 months ago
  1. 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
  2. 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.
katarinasupe commented 5 months ago

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.

Ana-Marija-design commented 5 months ago

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.

tonilastre commented 4 months ago

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:

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.

katarinasupe commented 4 months ago

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.

tonilastre commented 4 months ago

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!