Keystone 4 documentation

[Noviny]

We recently made a big push to update our documentation, as well as streamline the process of updating it in the future. To that end, we've redone the documentation site using gatsby, and have put it up on netlify.

What would be great is feedback on the documentation we've got. If you've got some time, a bit of a review would be amazing.

The most important pages to look at are:

• the getting started page
• yo generator guide
• setting up guide
• Documentation launch page

The questions I'm most interested in are:

• Can I find the information I want?
• Is the information clearly presented?

Feedback is welcome here, or if you find an issue you can solve, you can make a PR to the docs branch.

Thanks in advance!

[christroutner]

There are a lot of common pitfalls that aren't captured in the *yo generator guide*. Pitfalls such as specific versions of node to use or avoid, or having to install yo as sudo (I think, it's been a while). Add to this that the master branch of Keystone is often broken. That leads to a lot of frustration and a lack of adoption.

…

On Wed, Apr 5, 2017 at 6:37 PM, Ben Conolly ***@***.***> wrote: We recently made a big push to update our documentation, as well as streamline the process of updating it in the future. To that end, we've redone the documentation site using gatsby, and have put it up on netlify. What would be great is feedback on the documentation we've got. If you've got some time, a bit of a review would be amazing. The most important pages to look at are: - the getting started page <http://keystonejs.netlify.com/getting-started> - yo generator guide <http://keystonejs.netlify.com/getting-started/yo-generator> - setting up guide <http://keystonejs.netlify.com/getting-started/setting-up/part-1> - Documentation launch page <http://keystonejs.netlify.com/documentation> The questions I'm most interested in are: - Can I find the information I want? - Is the information clearly presented? Feedback is welcome here, or if you find an issue you can solve, you can make a PR to the docs <https://github.com/keystonejs/keystone/tree/docs> branch. Thanks in advance! — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <keystonejs/keystone#4181>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AJaej_X-zpIokLDsutrVzvpDplkTtYJtks5rtEHqgaJpZM4M1A6d> .

[Noviny]

@christroutner Just checking, are you flagging this as three separate issues?

1. Node version specification not provided
2. No information about sudo installing if you cannot globally install
3. Master branch of keystone is often broken

The third does not seem to be a generator or documentation issue, as the generator pulls a set version from npm, and doesn't interact with master.

[gcortese]

Hi - i would like to use keystone 4 for a project, can you please let me know if/what in the documentation you mention is up-do-date and 'reasonably' complete ?
Thanks a lot,
giovanni

[bill-kidwell]

I am a new KeystoneJS user. I have read a bit about Keystone in the past, and have been interested in looking at it for a while.

For some context, I have almost 20 years of software engineering experience, and the last 3 years have focused around JavaScript -- primarily React.js and d3.js

Here is my feedback on the Getting Started Page.

It provides you with an easy connection to mongoDB It wraps both mongoose and expresss, and provides more detailed database fields, with setups for common information patterns. Why? For the admin UI.

The first part of this sentence is a run-on. I think it is better as:
It provides you with an easy connection to mondoDB. [Keystone accomplishes this by wrapping] mongoose and express, providing more detailed database fields, and setups for common information patterns.

"Why? For the admin UI." doesn't make much sense to me at this point. You might need to expand on this to get your point across.

Keystone makes it easy to bring your own view engine, structure your routes however you want, and modify your data structures to suit you, all while making doing so easier.

You begin and end with easy here. Perhaps rephrase:

With Keystone you bring your own view engine, structure your routes however you want, and modify your data structures to suit you. Keystone makes it easy.

To answer your questions, this page provided me with the overview I needed. It gave me an idea of the technologies in play, and it pointed me to multiple ways to get started, from beginner to complex. With a few minor changes, I think this is good.

I will take a look at the yeoman guide next.

[bill-kidwell]

As previously mentioned, there is no mention or pre-requisites. I was unsure which version of node.js would work. I am using v6.11.2. I also ran into problems due to the lack of python.

I got a number of warnings when installing generator-keystone

$ npm install -g generator-keystone
npm WARN deprecated [email protected]: the module is now available as 'css-select'
npm WARN deprecated [email protected]: the module is now available as 'css-what'
npm WARN deprecated [email protected]: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue
npm WARN deprecated [email protected]: Please update to minimatch 3.0.2 or higher to avoid a RegExp DoS issue

NOTE: Please advise if I should open separate issues for these.

---

Upon creating a project with yo keystone, there were additional warnings.
There was also an error because I needed python on the path. I am unsure, based on the output whether that is optional or not. I recommend that you state it up front, and if it is not optional, that generator-keystone fails.

npm WARN deprecated [email protected]: letsencrypt-express has been renamed to greenlock-express and will now be maintained as such.
npm WARN deprecated [email protected]: Moved to localhost.daplie.me-certificates
npm WARN deprecated [email protected]: letsencrypt has been renamed to greenlock. Please find it at npm greenlock
npm WARN prefer global [email protected] should be installed with -g

gyp ERR! stack Error: Can't find Python executable "python", you can set the PYTHON env variable.

npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@^1.0.0 (node_modules\chokidar\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\ursa):
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] install: node-gyp rebuild
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: Exit status 1

---

Re: the structure, I found a couple of discrepancies between the generator's output and the docs. It may be due to the options that I chose. It also may be due to the python errors I saw. It might be wise to call that out if they are intentional.

I marked them with asterisks below.

|--lib  *not present*
|  Custom libraries and other code
|--models 
|  Your application's database models
|--public
|  Static files (css, js, images, etc.) that are publicly available
|--routes
|  |--api *not present*
|  |  Your application's api controllers
|  |--views 
|  |  Your application's view controllers
|  |--index.js 
|  |  Initialises your application's routes and views
|  |--middleware.js
|  |  Custom middleware for your routes
|--templates
|  |--includes *not present*
|  |  Common .pug includes go in here
|  |--layouts 
|  |  Base .pug layouts go in here
|  |--mixins
|  |  Common .pug mixins go in here
|  |--views
|  |  Your application's view templates
|--updates
|  Data population and migration scripts
|--package.json
|  Project configuration for npm
|--keystone.js
|  Main script that starts your application

---

The section on the User.js file appears to be out of date.
I assume the Relationships section is added as part of answering Yes to the blog option. I can leave that out and submit a pull request if the content below is correct.

var keystone = require('keystone');
var Types = keystone.Field.Types;

var User = new keystone.List('User');

User.add({
  name: { type: Types.Name, required: true, index: true },
  email: { type: Types.Email, initial: true, required: true, index: true },
  password: { type: Types.Password, initial: true },
  canAccessKeystone: { type: Boolean, initial: true }
});

User.register();

is now

/**
 * User Model
 * ==========
 */
var User = new keystone.List('User');

User.add({
	name: { type: Types.Name, required: true, index: true },
	email: { type: Types.Email, initial: true, required: true, unique: true, index: true },
	password: { type: Types.Password, initial: true, required: true },
}, 'Permissions', {
	isAdmin: { type: Boolean, label: 'Can access Keystone', index: true },
});

// Provide access to Keystone
User.schema.virtual('canAccessKeystone').get(function () {
	return this.isAdmin;
});


/**
 * Relationships
 */
User.relationship({ ref: 'Post', path: 'posts', refPath: 'author' });


/**
 * Registration
 */
User.defaultColumns = 'name, email, isAdmin';
User.register();

---

Here you start talking about settings in keystone.js (I think)

Authentication and Session Management
For Keystone to provide authentication and session management to your application, it needs to know a few things:

The option user model must be the name of the Model that Keystone should look in to find your users. If you use a different model name, be sure to set the option correctly.

but you don't mention keystone.js. Educated guess.

---

Routes & Views

Usually, the easiest and clearest way to configure the logic for different routes (or views) in your application is to set up all the bindings single file, then put any common logic (or middleware) in another file.

I think this should read "in your application is to set up all the bindings [in a] single file"

I'll pick up from here next time.

[bill-kidwell]

@Noviny,

Can you confirm this is the type of feedback you are looking for? I noticed a few things out of date, so if it is too early for things that low level... just let me know.

[Noviny]

@bill-kidwell

Honestly, anything you see that needs fixing, it would be amazing to get help with. The documentation has now been merged in to master, so if you see something on the new website that's wrong, make a PR to update it and tag me and I'll jump on it.

[zacharysang]

Does anyone happen to know if SSL setup docs are currently being worked on? I just went through the process of that setup and experienced some gaps (Eg: configuration settings that needed to be set, but not mentioned) that required me to read through the source to figure out. If this isn't something already in the works, I'd be happy to work on this myself!

[christroutner]

@zacharysang I also struggled trying to figure out SSL setup with KeystoneJS. I think I left a thread on the Google group with the results of my research. I eventually figured it out and wrote up this readme on how to setup Nginx and a Let's Encrypt SSL:

https://github.com/skagitpublishing/docker-connextcms/tree/master/nginx

The directions focus on ConnextCMS, running in a docker container, but it should work equally well for a KeystoneJS installation.

[internetErik]

This is what I did for SSL

let keystoneInit = {
  'name': 'Some Site',
  'brand': 'Some Site',
  'static': '../public',
  'view engine': 'hbs',
  'mongo': process.env.MONGO_URI || 'mongodb://localhost/some-site',
  'emails': 'templates/emails',
  'cookie secret': process.env.COOKIE_SECRET,
  'auto update': true,
  'session': true,
  'auth': true,
  'user model': 'User',
  'port': process.env.PORT || 3000,
};

if(process.env.NODE_ENV === 'production') {
  keystoneInit['ssl']      = true; // true to start both, 'only' to start only sll server
  keystoneInit['ssl key']  = process.cwd() + '/some.key';
  keystoneInit['ssl cert'] = process.cwd() + '/some.crt';
  keystoneInit['ssl ca']   = process.cwd() + '/some.pem';
  keystoneInit['ssl port'] = process.env.SSL_PORT || 443;
}

keystone.init(keystoneInit);

[zacharysang]

@christroutner @internetErik I guess I am referring more specifically to documenting the letsencrypt setup process via letsencrypt config. Following this article (and with some investigation of my own), I was able to fully setup SSL certificates using only environment variables (dotenv) and the configuration object passed into keystone.init({...}) all within keystone.js. This functionality is really powerful and helpful for setting up keystone, but some of the necessary details are currently missing from the docs. While there is overlap with the greenlock-express module, it may still be worth documenting the various config settings that can be included on the keystone side.

Here is an annotated version of my config object passed to keystone.init({...}). All of this achieves configuring the keystone application to automatically register and renew SSL certificates with letsencrypt on top of configuring ports and redirects:

'port': process.env.PORT || 3000,
'ssl port': process.env.SSL_PORT || 3001,
'ssl public port': 443, // different from `ssl port` if using iptables/ port forwarding
'ssl': 'force', // force redirects to https port 
'ssl cert': letsencryptPath + 'cert.pem', // path to generated certificate (generated at `$HOME/letsencrypt/etc` by default)
'ssl key': letsencryptPath + 'privkey.pem', // path to generated private key (same default as ssl cert)
letsencrypt: {
		email: '[email protected]',
		domains: '[email protected]',
		register: true, // whether or not to automatically register with letsencrypt
		tos: true, // agreeing to letsencrypt's Terms of Service
		production: process.env.PRODUCTION, /* specifies if keystone should use the staging letsencrypt certification server or the production one (it is advised to be used during setup to avoid hitting the rate limit). Values should be `false` for staging (I excluded the .env variable since any value is read in as a string) or `true` for production ( :) ) */
}

[htor]

Not sure what system is used to generate / write this documentation, but i have a couple of suggestions.

1. As part of streamlining the process of updating the docs, maybe we should start versioning the docs - at least for the API section?

A little drop-down or selector with v3, v4 could point to the relevant versions of documentation that are compatible and people would be less confused if the older docs didn't disappear from history, as they may rely on them. The older versions would have a reference, as well as the newest.
A lot of popular libraries do this today: https://vuejs.org/v2/api/, https://docs.angularjs.org/api.

2. The docs seems to be spread out everywhere in markdown files in the source code directories outside of docs. See for example https://github.com/keystonejs/keystone/tree/master/fields and https://github.com/keystonejs/keystone/tree/master/fields/types/password has their own README.md. Is this the preferred way, or having the documentation in docs? I suggest having everything in the docs directory, as it is more common in software projects.

[apoorvkapil]

Installation guide to keystonejs 4.0 beta is ambiguous and doesn't give proper insight how to install it.

I have used below command

npm init

npm install --save keystone@next

It's just listed all node modules and didn't get any core keystone files to start or build the project.

[stennie]

@htor As mentioned at the start of this discussion, the documentation is now a static site built using Gatsby. I couldn't find info on how to build the docs, so created #4654 (Add guide for building Keystone 4 docs) with some quick instructions.

Since the new documentation has been merged to master a while ago, I'm going to create & link separate tracking issues for any lingering suggestions from this discussion thread so the remaining tasks are clearer. If anyone has suggestions for documentation improvements, please create a new issue.

If anyone is interested in contributing to Keystone 4 documentation, please join the KeystoneJS Community Slack for feedback and discussion.

Regards,
Stennie