Next steps after quickstart

[zepatrik]

Is your feature request related to a problem? Please describe.

there definitely needs to be a better documentation regarding the first start of using keto :)

• how should the namespaces be structured (schema)
• how is keto namespace migrate up working

basically, what are the required steps to get keto up and running. I got it now working (gRPC + v0.6). but it was a try&error marathon

Describe the solution you'd like

second step after the quick start, where it is explained how to customize everything and where to start doing your own stuff

[...] a small guide with the steps needed to be done:

1. Customize config (add ports, hosts, namespaces, database, etc.)
2. Add namespace to keto by executing keto namespace migrate up
3. Connect your application to the keto server

[johanforssell]

This is basically a "me too" post, which I know is frowned upon.

So I would like to point out how the current documentation is lacking, with some constructive criticism:

1. Reading https://www.ory.sh/keto/docs/examples/olymp-file-sharing you come across this note
2. Following the "namespace" link we arrive at https://www.ory.sh/keto/docs/concepts/namespaces, which states

   Namespaces have a configuration that defines the relations, and some other important values (see reference).

3. The "reference" link leads to https://www.ory.sh/keto/docs/reference/configuration, which contains the following section on namespaces:

   ## namespaces ##
   #
   # Namespace configuration or it's location.
   #
   # Default value: file://./keto_namespaces
   #
   # Set this value using environment variables on
   # - Linux/macOS:
   #    $ export NAMESPACES=<value>
   # - Windows Command Line (CMD):
   #    > set NAMESPACES=<value>
   #
   namespaces: http://a.aaa
   

Feedback

• The config file example should ALSO mention that you can specify the configuration right there, like the example in https://github.com/ory/keto/blob/master/contrib/cat-videos-example/keto.yml
• The config file example should actually show the configuration format for namespaces, or perhaps a specific example.
• The Guides section should show the different ways to define namespaces.
• The Quickstart: Cat Videos Example should mention the namespace concept somewhere in the text

[zepatrik]

Thanks for the criticism, it is constructive indeed :+1: Those are exactly the kind of problems I hoped to find with this issue, as it is quite hard to figure that out if you are deep in the topic. Thanks :+1:

[johanforssell]

Also - describe the a namespace migration. What is it and how is it done.

EDIT: Oops, I see that this was already in the original text

[github-actions[bot]]

Hello contributors!

I am marking this issue as stale as it has not received any engagement from the community or maintainers for a year. That does not imply that the issue has no merit! If you feel strongly about this issue

• open a PR referencing and resolving the issue;
• leave a comment on it and discuss ideas on how you could contribute towards resolving it;
• leave a comment and describe in detail why this issue is critical for your use case;
• open a new issue with updated details and a plan for resolving the issue.

Throughout its lifetime, Ory has received over 10.000 issues and PRs. To sustain that growth, we need to prioritize and focus on issues that are important to the community. A good indication of importance, and thus priority, is activity on a topic.

Unfortunately, burnout has become a topic of concern amongst open-source projects.

It can lead to severe personal and health issues as well as opening catastrophic attack vectors.

The motivation for this automation is to help prioritize issues in the backlog and not ignore, reject, or belittle anyone.

If this issue was marked as stale erroneously you can exempt it by adding the backlog label, assigning someone, or setting a milestone for it.

Thank you for your understanding and to anyone who participated in the conversation! And as written above, please do participate in the conversation if this topic is important to you!

Thank you 🙏✌️