cockroachdb / docs Goto Github PK
View Code? Open in Web Editor NEWCockroachDB user documentation
Home Page: https://cockroachlabs.com/docs
License: Creative Commons Attribution 4.0 International
CockroachDB user documentation
Home Page: https://cockroachlabs.com/docs
License: Creative Commons Attribution 4.0 International
Document all options.
Making the links relative will make it easier to set up a staging environment as well as (automatically) testing before pushing upstream. Any thoughts?
Currently the BNF generator has a few steps:
This is because before we had to use an external program for step 1. Now that we have our own parser, there's no need to convert to EBNF and back. Instead we can simplify the yacc AST in memory and only output an EBNF once.
We should at the very least have the following:
cockroach cert
command:
create-node
and create-client
need ca.crt
and ca.key
)@mberhault will do a writeup and coordinate with @jseldess for integration into the docs.
Explain how our docs work (Jekyll, style guide, etc.).
Note from @bdarnell:
For comparison, mongodb's docs are under ShareAlike-NonCommercial; I checked cassandra/datastax and hbase but it was not immediately obvious what license their docs used. Tornado uses Attribution-only.
Note from @petermattis: The CC BY license sounds good to me. If Apache-style restrictions (or lack thereof) are good enough for our code they should be good enough for our docs.
You can't access http:\\<docker ip>:26527
because docker ports/networking something something. I think we need more to the docker invocation than what's documented here. I think @tschottdorf would know.
Also we need to figure out the relationship between the installation instructions we have in the README.md and the docs site.
In the grammar diagram itβs not too obvious for me which nodes are links to expansions. Maybe render them blue and underlined?
Instructions for deploying a multi-node cluster in the cloud (at least AWS).
Breakdown of architecture - concise, clear, and with diagrams. Based on CockroachDB design doc.
Matrix comparing CockroachDB against other databases. Need to identify the most important points of comparison. Likely to included:
@spencerkimball, @petermattis, @bdarnell: Can you help me identify other points of comparison as well as the dbs that we want to compare against?
To be part of the SQL Reference section.
Related docs:
For users who don't use Prometheus, our 2.0 monitoring docs should probably cover:
/health
HTTP endpoint for node health.<hostname>:8080/_status/vars
HTTP endpoint used by Prometheus. The format is easy-to-parse format, so users could massage the data to work with different monitoring system.<hostname>:8080/#/debug/
, thought those pages are under construction and not exposed by default. To access them, you must first run SET CLUSTER SETTING server.remote_debugging.mode = 'any';
.@dianasaur323, any thoughts or comments?
On mobile and tablet, the critters should stack vertically.
http://www.cockroachlabs.com/docs/
cc: @knz
Need to update Start a Local Cluster. See:
#4269 - see below
#4335 - default --stores
value for cockroach start
#4352 - remove --dev
mode for cockroach start
cockroach start
is specified then the server only listens on localhost and the server starts in insecure mode. This allows a developer running a local instance to start cockroach with no additional arguments.cockroach start --insecure
is specified the server listens on all addresses and starts in insecure mode. This forces a production cockroach cluster composed of multiple nodes to explicitly specify --insecure
.cockroach start --cert-file
is specified the server listens on all addresses and starts in secure mode.Document most important sql commands for getting up and running with CockroachDB.
We need to get HTTPS working with the entire website. Currently it is returning a bad cert error. One solution would be to put cloudflare in front of the whole thing (my recommendation).
Right now, lines are wrapping. Instead, we should probably change the css so lines continue with a horizontal scrollbar.
cc: @knz
Full reference docs for sql statements. To be part of the SQL Reference section.
Draft page here: http://www.cockroachlabs.com/docs/sql-statements.html
Need to provide horizontal scroll when screen in narrower than a table,
Docs on how to contribute to cockroachdb docs and development.
So our product promises to behave nicely assuming the user is storing their files in a properly-behaved filesystem / persistent storage.
However as discussed in this paper: https://www.usenix.org/system/files/conference/osdi14/osdi14-paper-pillai.pdf
operating systems have bugs in how they implement file systems, and sometimes the OS promises that data written by an application is actually written to disk while there is a bug which causes this data to not be saved. Or the OS promises something about the order in which I/O operations issued by the DB are performed on disk, and instead actually does things in a different order. This is Real Bad.
Our docs need to explain what we assume from the underlying storage and make recommendations about which file systems are known to work sufficiently well.
Should be part of the SQL Reference section.
Our current docs search opens a Google results page. We should find a way to keep the results within the frame of our docs site, and style the results to be in line with the rest of the site.
Aerospike's search results can serve as an example: http://www.aerospike.com/docs/
cc: @jess-edwards, @bdarnell
Github Pages will soon support only the kramdown dialect of markdown and rouge as syntax highlighter. We need to make some updates to the configuration file and code block formatting.
https://github.com/blog/2100-github-pages-now-faster-and-simpler-with-jekyll-3-0
cc: @mjibson
When you scroll down a large page in Safari, the mobile topnav menu flashes along the right margin of the page. @dt mentioned that Safari, unlike Chrome, loads the content as you scroll. We could solve this by limiting that version of the topnav to mobile devices, not just by screen width.
Sample page: https://www.cockroachlabs.com/docs/sql-grammar.html
Instructions for starting a local cluster in various ways:
Link away for starting up multi-node cluster across machines.
There needs to be a way to search across all topics in the docs.
Always planned to get it in there, but just occurred to me that this is pretty important for beta, @spencerkimball and @jess-edwards. Will look into options.
It's pretty common for docs to be at docs.company.com, so we should make sure that when users go to docs.cockroachlabs.com, they get redirected to cockroachlabs.com/docs.
@mberhault, can you help with this at some point?
Many deployments will need to increase the file descriptor limit, and possibly other ulimit settings. This is true of large deployments on linux and even small ones on OSX. We should have a document explaining this along with other recommended system-level settings.
For comparison, https://docs.datastax.com/en/cassandra/2.0/cassandra/install/installRecommendSettings.html
Rework features pages to support new website messaging/benefits.
Currently, when a line of code is longer than than the screen allows, the line wraps. This makes certain samples harder to read.
Adjust the css to prevent line-wrapping; offer a horizontal scrollbar instead.
Concise answers to questions we think prospects might be most immediately interested in, such as how does cockroach scale, how does it survive failures, why is is sql, etc.
To be part of the SQL reference section. Explain rules for identifiers and keywords.
Work with DivisonOf to establish brand-specific styling for callouts in docs (tips, notes, warnings).
In the cockroach README there's a talks list. What do you think about adding these as a subsection in the docs?
Call out recommended postgres drivers (those we've tested) for:
Also mention that any postgres driver should work and suggest getting in touch if any problems.
We should put in place an automated test on Jekyll output. Ideally, the test would run immediately following jekyll serve
or jekyll build
. At a minimum, the test should catch broken links and broken images.
This might do the trick: https://github.com/gjtorikian/html-proofer
Show how to connect and perform basic sql commands from various language (python, ruby, c, javascript, go).
Should be part of the SQL Reference section.
For OS X and Linux, Download the Binary needs a valid link.
@bdarnell, @mberhault: When do you think OS X and Linux binaries will be ready, and where will we host them for user download?
Cockroach PR 4027 removes --init and changes --gossip to --join. Need to update Start a Local Cluster.
We need to add a sitemap to make sure Google and other search engines know about the organization of our site.
It might be best to start by having GitHub automatically generate our sitemap: https://help.github.com/articles/sitemaps-for-github-pages/.
Here are the docs for the plugin itself: http://www.rubydoc.info/gems/jekyll-sitemap/0.10.0
Our Jekyll theme has a built-in function to add a toc to the top of a page; you just add toc:true
to the front-matter. Currently, it adds the toc to the very top of the page, above all other content. We should think about:
cc: @jess-edwards
Figure out how to provide docs for multiple versions of CockroachDB
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.