Skip to content

Initial split of get started -> local into user guides#309

Merged
morgo merged 13 commits intovitessio:prodfrom
planetscale:morgo-update-local
Nov 2, 2019
Merged

Initial split of get started -> local into user guides#309
morgo merged 13 commits intovitessio:prodfrom
planetscale:morgo-update-local

Conversation

@morgo
Copy link
Copy Markdown
Contributor

@morgo morgo commented Oct 18, 2019

This is a documentation refactor. Let me explain the motivations:

  • The current user-guides are not very task-oriented (Improve User Guides #263). User guide should mean "here is a set of steps to achieve a specific goal".
  • Part of this is due to the use of shell scripts like ./301_customer_sharded.sh. i.e. there is no expressive API that is truly universal (context is key, including working directory). We should be making this script obsolete. i.e. instead of:
set -e

./lvtctl.sh ApplySchema -sql-file create_commerce_seq.sql commerce
./lvtctl.sh ApplyVSchema -vschema_file vschema_commerce_seq.json commerce
./lvtctl.sh ApplySchema -sql-file create_customer_sharded.sql customer
./lvtctl.sh ApplyVSchema -vschema_file vschema_customer_sharded.json customer

disown -a

.. we make sure that vtctlclient accepts a config file (issue vitessio/vitess#4921) and replace the script with a manual page that shows a solution that works for all deployment methods:

vtctlclient ApplySchema -sql-file create_commerce_seq.sql commerce
vtctlclient ApplyVSchema -vschema_file vschema_commerce_seq.json commerce

vtctlclient ApplySchema -sql-file create_customer_sharded.sql customer
vtctlclient ApplyVSchema -vschema_file vschema_customer_sharded.json customer

If we do this, the examples also become more portable.. since I can figure out how to apply them to my use case without copying the whole examples directory.


So now to describe what is changed here:

  • The local guide only covers deployment, and then suggests a next step.
  • The next step of Vertical split uses MySQL from a global location (because the local guide showed how to setup mysql cli config).
  • The user guides for vertical split and horizontal split are closer to deployment scenario agnostic (closer but not there yet. The goal should be that one could go from the Kubernetes or Vagrant deploy guide straight to here too, with one version to maintain.)

Also:
Fixes #298
Fixes #315

Long term this will also lead to less duplicate content, since there is overlap between kubernetes and local. It will also make it easier to add deploy guides for every cloud deployment scenario separately (GKE, EKS, Azure, etc.) without the duplicate content.

morgo added 4 commits October 18, 2019 10:13
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
@morgo morgo changed the title Initial split of local guide Initial split of get started -> local into user guides Oct 18, 2019
@morgo morgo marked this pull request as ready for review October 18, 2019 17:14
@morgo morgo requested a review from sougou October 18, 2019 17:16
Signed-off-by: Morgan Tocker <tocker@gmail.com>
@sougou
Copy link
Copy Markdown
Contributor

sougou commented Oct 19, 2019

Some thoughts and comments:

  • A downside of this approach is that the storyline gets lost. If someone starts off with "Getting Started", they can get lucky and follow the full story. But someone directly jumping into horizontal resharding may find it confusing. I don't have a better alternative yet though.

  • 401_teardown.sh doesn't clean up everything. Some of the cleanup is done by 206_clean_commerce.sh. We need to address that part.

  • I like the mysql launch improvement. We should definitely do the same thing for vtctlclient.

@morgo
Copy link
Copy Markdown
Contributor Author

morgo commented Oct 22, 2019

  • A downside of this approach is that the storyline gets lost. If someone starts off with "Getting Started", they can get lucky and follow the full story. But someone directly jumping into horizontal resharding may find it confusing. I don't have a better alternative yet though.

I did put an Info tag to suggest using vertical first, but there could be some troubleshooting, because it will get ignored based on this pattern.

  • 401_teardown.sh doesn't clean up everything. Some of the cleanup is done by 206_clean_commerce.sh. We need to address that part.

I can fix this in code. I will modify 401 to also do 206_'s work if required.

  • I like the mysql launch improvement. We should definitely do the same thing for vtctlclient.

Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
morgo added 6 commits October 27, 2019 15:13
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
Signed-off-by: Morgan Tocker <tocker@gmail.com>
@morgo
Copy link
Copy Markdown
Contributor Author

morgo commented Nov 2, 2019

@sougou 401_teardown can now start from any point. Do you have any issues if we merge this PR?

@morgo morgo merged commit 5d22987 into vitessio:prod Nov 2, 2019
@morgo morgo deleted the morgo-update-local branch November 2, 2019 20:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Investigate Centos 7 get started tutorial Update local tutorial (Run Vitess locally)

3 participants