vitessio/website

vitess.io website and other project management related content

website's Issues

Broken links

On page https://vitess.io/docs/overview/scalingwithvitess/
the following links don't work:

Horizontal sharding (Codelab)
Sharding in Kubernetes (Codelab)

They should probably point back to the tutorials - local and kubernetes respectively.

Add new flag option pages

Fairly often I want to reference flags for vtgate, vttablet, etc. We already have decent descriptions for the help docs, so it shouldn't be too difficult to output those to the website. We could copy them out for now, but it's probably best long term to autogenerate them from the main repo so they don't go stale.

I think that this is the perfect example: https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/configmap/. It shows the flag, type and default value in an easy to reference table, hyperlinked to the description.

File a DNS ticket for blog.vitess.io to go to new blog

Instead of the blogspot

Sequence documentation is incorrect

https://vitess.io/docs/reference/vitess-sequences/
We have the following content on this page which is incorrect. This needs to be corrected.

In a sharded keyspace, a Sequence’s data is only present in one shard (but its schema is in all the shards). We configure which shard has the data by using a keyspace_id for the sequence, and route all sequence traffic to the shard that hold that keyspace_id. That way we are completely compatible with any horizontal resharding.

Sequences are documented correctly in the tutorial:
https://vitess.io/docs/tutorials/kubernetes/

The sequence table is an unsharded single row table that Vitess can use to generate monotonically increasing ids.
Since sequences are unsharded tables, they will be stored in the commerce database.

Add third column in docs

Nothing urgent, but the third column navigation that exists in the user guides is missing from the vtctl and api reference pages.
https://vitess.io/docs/reference/vtctl/#executefetchasdba

Vitess API reference doc needs to be reviewed and corrected

The Vitess API reference doc looks old. It refers to v3 API as alpha. The entire doc should be reviewed and brought up to date.

Add scaffolding for documentation versions

We need to make it easy to archive user documentation like so:

• /latest-version/sectionname
• /2.2/sectionname

Update "Edit" on vitess.io

The edit link allows you to edit in GitHub, but I believe doing so will create commits without a DCO:

#227

This appears to be a known problem:
todogroup/gh-issues#50

Maybe we should remove the edit link, and just have a create issue link?

Add community page

Add a community page at vitess.io/community modeled after Envoy's.

Preliminary content in GDocs.

Fix display of presentation files in resources section

Introduction of third column has broken most presentation widths.

Explanation gif for the homepage

I think this gif from the Square post is super helpful when describing Vitess. I think we should make a better version of it and put it on the homepage. Maybe you could make a companion image with more detail for the docs that shows more details about vtgate -> vttablet, etc.

Edit links are broken after i18n support

The "Edit" (in GitHub) links on the public docs are broken. For example, this page links to https://github.com/vitessio/website/tree/master/content/docs/_index.md but after #195 this should now be https://github.com/vitessio/website/blob/master/content/en/docs/_index.md.

cc @lucperkins

Clean up blog posts

• remove tds and spans

Add Quick Start doc in Hugo readable file

Bug in social media links on /docs page

Social media in /docs page navbar throw out empty values, even though params are assigned correctly in the config file.

Check Content in Getting Started section

All links checked except for the links referring to sharding. Remember to fix.

Edit out severe inaccuracies from Vitess site

Follow Jiten's list

Document "MySQL Compatibility"

Add a page under "Reference" which clearly explains MySQL compatibility story. Rename https://vitess.io/docs/reference/mysql-server-protocol/ to fit in this page.

Add redirect rules for all user guides

Example of broken links

https://vitess.io/getting-started/local-instance/
https://vitess.io/user-guide/horizontal-sharding-workflow/

Rename default branch to 'prod'

GitHub's robots.txt explicitly permits indexing the branch called 'master'. This is fine for source code, but for docs it creates a duplicate content problem in search engines.

It is also better to have Search Engines index https://vitess.io/docs/ instead of GitHub because we can add redirection if content needs to be moved around.

I suggest we rename the default branch to 'prod' to fix this.

@lucperkins is this something you mind helping with?

See also:
https://stackoverflow.com/questions/15844905/how-to-stop-google-indexing-my-github-repository

Check content in Schema Management section

• Links
• Check why weight isn't showing the 2 docs in the right order

Add new presentations to resources

new slides and info

Add keyrange calculator

It's not necessary, but it would be convenient if on the sharding page, there were a little calculator that would help you define your keyranges. I would input the number of desired shards, and it would output all of the shard names for an equal split.

Add Vitess Calendar to Vitess website

We have created a Vitess Calendar that lists the Vitess Monthly Meetings and will list Vitess Meetups.

We would like to make this available on the Vitess website so that the Vitess Community can add it to their calendars and stay up-to-date on events.

https://calendar.google.com/calendar/embed?src=planetscale.com_21541iv1dn67m0jd023lql4dak%40group.calendar.google.com&ctz=America%2FLos_Angeles

Update Slack logos everywhere on website

To new logos found here

They need to be updated in:

• header
• footer

Note the different styles (in white)

Check content in Sharding section

• Links
• Organisation of content

Documentation correction

I noticed what seems to be a typo in the documentation for the "Run Vitess Locally" tutorial. It states the following:

if you ran make build while in $HOME/vt/src/vitess.io/vitess, then you should set: export VTROOT=$HOME/vt

Then later the same tutorial has us run a 101_initial_cluster.sh script which in turn eventually runs a vttablet_up.sh script. In the vttablet_up.sh script we see references to VTROOT such as:

init_db_sql_file="$VTROOT/config/init_db.sql"

It seems based on this that VTROOT should be pointed directly at the vitess repo root folder, not to a folder that would precede src/vitess.io/vitess.

Please correct me if I'm wrong, but it seems like the documentation should instead say:

if you ran make build while in $HOME/vt/src/vitess.io/vitess, then you should set: export VTROOT=$HOME/vt/src/vitess.io/vitess

If this seems right I would be happy to issue a PR with the change to correct this.

@avaidyanatha ?

FAQ: Common Scenarios

Relating to the thread with @sabutai's question on Slack (referencing this issue):

• Add info about the workaround

sabutai   [15 hours ago]
For others who may be interested: We've found a workaround for this: By using Eclipselink QuerySequence, we were able to define a query to Vitess Sequences tables directly. This not only prevented SELECT LAST_INSERT_ID() call, we were also able to reduce number of DB trips since the application could request a bunch of IDs from Vitess, let's say 1000, so it will make only one call per 1000 inserts.

action: put faq for common scenarios back online

Check content in Overview section

• What is Vitess
• Scaling MySQL With Vitess
• Key Vitess Concepts
• Edit Index page

Links to fix in 'Getting Started'

In Run Vitess with Kubernetes

• Backup link in "Note: The --scopes storage-rw argument is necessary to allow built-in backup/restore"
• In no 13, "start vtgate" - check link to anchored link on concepts page
• In "Try Vitess resharding", check links here once the sharding section is replaced

Many of the Kubernetes links no longer exist, but we may no longer need these instructions so I will leave it for now.

Arrange and clean documentation

• Strip out Jekyll-specific stuff
• Reorganize folder hierarchy so we don't end up with content/docs/doc
• General housecleaning

Reorganize Documentation TOC

On the Vitess monthly call today, I proposed adjusting the Vitess documentation table of contents to use DITA information typing + common elements seen in other technical docs (slides).

This includes the following changes to structure:

• Merge “The Vitess Documentation” and “Overview” (can't do for now: the web system doesn't support it; and "The Vitess Documentation" works well as an Index).
• Rename “Tutorials” to “Get Started” #221
• Move “Concepts” to top level
• Move “FAQ” to top level #223
• Remove “Sharding” and “Advanced Features” (these become concepts, reference or user guides) #224
• Remove “Schema Management” #262
• Remove “Launching” #262

Not in scope for now:

• Adding “Releases”
• Moving “Resources” (it is not very common, but makes sense to me for now.)
• Copy of docs per-version

Add recent content to Resources page

The Resources page has content up to October 2018. We should add the following recent content:

• Derek Perkins / Nozzle.io on Cloud Native show
  https://anchor.fm/cloud-native-show/episodes/Vitess-at-scale---how-Nozzle-io-runs-MySQL-on-Kubernetes-e4m5lo
• Sugu CNCF Webinar https://youtu.be/E6H4bgJ3Z6c
• JD.com at Kubecon 19 China
  How JD.Com runs the World's Largest Vitess
  https://www.youtube.com/watch?v=qww4UVNG3Io
• Jiten at RootConf
  OLTP or OLAP: why not both? https://youtu.be/bhzJJF82mFc
• Sugu @ Percona Live https://www.youtube.com/watch?v=v7oxiVmGXp4
• David Cohen (Intel) @ Percona Live
  https://www.percona.com/live/19/sessions/an-open-source-cloud-native-database-cndb
• Vitess Deep Dive @ Kubecon 19 Europe https://www.youtube.com/watch?v=OZl4HrB9p-8
• Meetup at Slack HQ, co-hosted by Planetscale
  • Vitess: New and Coming Soon! Deepthi Sigireddi (TODO: get slides from @deepthi)
  • Deploying multi-cell Vitess, Rafael Chacon Vivas (TODO: get slides from @rafael)
  • Vitess at Pinterest, David Weitzman https://www.youtube.com/watch?v=1cWWlaqlia8
  • No more Regrets, Sugu https://www.youtube.com/watch?v=B1Nrtptjtcs

Review: Run Vitess locally

Please review "Run Vitess locally" -

• Is this still accurate?
• any changes to be made / proposed?

Remove SBR support

• remove all schema swap documentation
• remove references to SBR
• put up a banner with an SBR deprecation notice

Check content in User Guides section

• All links
• All code blocks display

Add Manual Build as hugo readable file

Replace Slack logo in nav and footer with color version

Add Pinterest to list of users in front page

• Add Pinterest logo

Update tagline on blog page

Updates and insights from the Vitess team

Investigate better ways to do presentation display

Old site had GViewer, which is no longer working well.

I switched the presentations section to ViewerJS, with the files hosted in the static directory.

The current dimensions / usage of ViewerJS is not working well on mobile devices.

@lucperkins can you help me look into optimizing the presentations page experience with ViewerJS or other tools?

VSchema advanced usage is inconsistent with tutorial

https://vitess.io/docs/schema-management/vschema/#advanced-usage
Since we changed the local example (vitessio/vitess/examples/local), this part of the documentation is now out-of-date. The new local example does not actually illustrate the advanced usage, so we may need to enhance that.
Or possibly this will be covered by the vreplication example once we are able to mainstream that.

Add documentation for metrics and per-user stats

Admins seek ability to associate specific users with specific queries and overall usage.
Table ACLs enable this. And vitess exports per-user stats.
Vars are listed here: https://github.com/vitessio/vitess/blob/master/go/vt/vttablet/tabletserver/tabletenv/tabletenv.go#L35

Here's the config: https://github.com/vitessio/vitess/blob/master/go/vt/vttablet/endtoend/main_test.go#L174

More:
If you look in /debug/vars you'll see a few variables that start with User, like UserTableQueryCount. It's a multi-dimentional export categorized by Table, User and query type. You'll find similar names exported as prometheus metrics.

If you see an incident, looking at these variables will help you quickly narrow down the root cause because of how fine-grained these stats are.
Once you've identified the table and query type, you can further drill down int /queryz (human readable) or /debug/query_stats (JSON), to see if it's a particular query.

Change baseurl to vitess.io when ready to go

In config.toml

Replace: Join Vitess Slack link

Currently, vitess.slack.com in top right goes to a login page.

The proper link to joining Vitess Slack as a new user is here.

Or: bit.ly link.

Thoughts on how to do this? (Given that the slack link is coming from a param in the config file)

Change schema swap to pt-osc or gh-ost

Via https://vitess.io/docs/schema-management/:

Note that this functionality is not recommended for long-running schema changes. In such cases, we recommend to do a schema swap instead.

The link to schema swap is also broken. We should change this to:

Note that this functionality is not recommended for long-running schema changes. In such cases, we recommend to use pt-online-schema-change or gh-ost instead.

Replace: Getting Started with k8s

Replace: "getting started with Kubernetes" with just one command.

@sougou - what is it? :)

Multiple vtgate setups in local machine using docker

Hi Team,

Please help me with the steps of configuring multiple vtgates in my local machine through docker.
Is it possible to do so?

Docs reorg

Delete

• Getting Started section
• Sharding section

Keep

• Manual build (from Getting Started)

Add

• Getting Started: with Minikube example

Edit

• Run Vitess locally: manual build+customized doc(minikube->local scripts) - add Deepthi's scripts

Broken redirect

https://vitess.io/docs/user-guides/server-configuration/