[refactor doc] Refactor the hosted npm documenation and update it to …

…be more current. Fixes #133.
nodejitsu · Oct 13, 2014 · 2fa4306 · 2fa4306
1 parent 3e9d75a
commit 2fa4306
Show file tree

Hide file tree

Showing 5 changed files with 169 additions and 116 deletions.
diff --git a/content/npm/best-practices.md b/content/npm/best-practices.md
@@ -0,0 +1,37 @@
+This is meant to be a non-exhaustive list of best practices when using `npm`.
+
+### Publish modules using `publishConfig`
+
+The `publishConfig` in your package.json does the following (from the [npm documentation](https://github.com/isaacs/npm/blob/master/doc/files/package.json.md#publishconfig)):
+
+> This is a set of config values that will be used at publish-time. It's especially
+> handy if you want to set the tag or registry, so that you can ensure that a given
+> package is not tagged with "latest" or published to the global public registry by default.
+>
+> Any config values can be overridden, but of course only "tag" and "registry" probably
+> matter for the purposes of publishing.
+
+For example:
+
+``` js
+  {
+    "publishConfig": { "registry": "https://your-subdomain.registry.nodejitsu.com" }
+  }
+```
+
+The benefits of using `publishConfig` is that it avoids accidental publishes to the public registry due to user error. Take for example a developer on your team who has not properly configured their machine by running `npm config set registry` or using the `--reg` flag. _That command would send your code public._ By using the `publishConfig` property you avoid that because it is part of your application.
+
+### Don't run `npm install` on your production machines
+
+The calculus of [semver][semver] (semantic versioning) makes `npm install` dangerous on your production machines. Here's an example:
+
+1. You deploy your code to five machines at the same time. Everything is great
+2. The next day you spin up two more machines.
+3. In that day, a new version of a dependency was released.
+
+Now your production machines have different dependencies satisfying the same `package.json` for your application. The solution? **Deploy a pre-built tarball** using something like `module-foundry`. `module-foundry` was developed by Nodejitsu for its Platform-as-a-Service product and you can think of it as "npm install as a service": you send it a package.json and it will return you a fully built tarball. For more information on [module-foundry checkout the Github repository][module-foundry]
+
+[meta:title]: <> (npm Best Practices)
+
+[module-foundry]: https://github.com/nodejitsu/module-foundry
+[semver]: http://semver.org
diff --git a/content/npm/cli.md b/content/npm/cli.md
@@ -15,15 +15,14 @@ Most of the workflow of npm is being done in the command line, we will show you
 First we need to setup our npm client to use your Private npm registry, with the following commands your local npm client will be ready to work with Private npm.
 
 ```
-$ npm config set always-auth true
-$ npm config set strict-ssl true
-$ npm config set ca ""
-$ npm config set registry https://<your-subdomain>.registry.nodejitsu.com
+npm config set always-auth true
+npm config set ca ""
+npm config set registry https://<your-subdomain>.registry.nodejitsu.com
 ```
 After setting this options you'll need to login by running:
 
 ```
-$ npm login
+npm login
 ```
 
 This will sync your Public npm user with our Private npm product.
@@ -39,44 +38,44 @@ Next we will learn how to use npm for common package management.
 If you want to install a package from your private or public registry you'll want to run:
 
 ```
-$ npm install <package-name>
+npm install <package-name>
 ```
 
 ![Install Package](https://versions.nodejitsu.com/id:handbook/resources/npm/npm_install.gif)
 
 
 Also if you want to save the package dependency in your package.json file just append the `--save` option to the command.
 ```
-$ npm install <package-name> --save
+npm install <package-name> --save
 ```
 
 Or if the package is a development dependency (like grunt, karma, etc.) you'll want to append `--save-dev` instead.
 
 ```
-$ npm install <package-name> --save-dev
+npm install <package-name> --save-dev
 ```
 
 ### Publish Package
 Publish a package is so easy with npm, just run the following command to publish a package to your private registry (make sure you followed the setup steps properly).
 
 ```
-$ npm publish
+npm publish
 ```
 
 ![NPM publish](https://versions.nodejitsu.com/id:handbook/resources/npm/npm_publish.gif)
 
 But if you want to publish the package to the public registry you can use the `--reg` option to define the npm registry to use.
 
 ```
-$ npm publish --reg https://registry.npmjs.org
+npm publish --reg https://registry.npmjs.org
 ```
 
 ### Unpublish Package
 
 If you want to unpublish a package you'll want to run:
 
 ```
-$ npm unpublish <package-name> --force
+npm unpublish <package-name> --force
 ```
 
 Take into account that if you want to publish the package again you'll need to use a different version name in your package.json to avoid conflicts.
@@ -90,7 +89,7 @@ Work in a team is awesome right? With npm, team management is easy too!
 If you want to know the maintaners of a package run:
 
 ```
-$ npm owner ls <package-name>
+npm owner ls <package-name>
 ```
 
 ![NPM owner](https://versions.nodejitsu.com/id:handbook/resources/npm/npm_owner_ls.gif)
@@ -100,7 +99,7 @@ $ npm owner ls <package-name>
 If you want to add a maintainer you'll need to run:
 
 ```
-$ npm owner add <username> <package-name>
+npm owner add <username> <package-name>
 ```
 
 ![Add Maintainer](https://versions.nodejitsu.com/id:handbook/resources/npm/npm_owner_add.gif)
@@ -111,10 +110,10 @@ $ npm owner add <username> <package-name>
 And if you want to remove a maintainer, run:
 
 ```
-$ npm owner rm <username> <package-name>
+npm owner rm <username> <package-name>
 ```
 
 **Protip**: Instead of manually adding each user to packages, for any private package you publish you can use the [Web Interface](web#sync-maintainers) to `Sync Maintainers`. This will allow all the users associated with your registry to have publish rights on all your private packages!
 
 
-[meta:title]: <> (Command Line Interface)
+[meta:title]: <> (Using the npm CLI)
diff --git a/content/npm/faq.md b/content/npm/faq.md
@@ -6,6 +6,22 @@ Yes, it will remain online and you will be able to use `npm` without problems.
 ### Can anyone else access my registry?
 Only the team members defined in the Web Interface can access your registry.
 
+### Why do I need to do change your `npm` CLI configuration?
+
+Because Nodejitsu's private npm works on two simple assumptions:
+
+* *Every request requires authentication:* This means that users you have not authorized cannot download packages from your private npm. Since this is not the default behavior of the public npm you need to set:
+
+```
+npm config set always-auth true
+```
+
+* *We have our SSL certificates*: Our private npm registry has it's own FQTLD using a multi-level wildcard certificate issued by [DigiCert](http://www.digiserver.com/) and serves `https://*.registry.nodejitsu.com`, so you'll need to tell the `npm` CLI to allow for standard global Certificate Authorities (CA):
+
+```
+npm config set ca ""
+```
+
 ### How can I make sure I don't accidentally publih to the public registry?
 We recommend that you set the default to private npm registry. This removes even the slightest chance that your private code could get published publicly accidentally.
 
@@ -33,10 +49,24 @@ The `publishConfig` in your package.json does the following (from the [npm docum
 > matter for the purposes of publishing.
 
 ### What happens if I need to change my password on the public npm registry?
-You will need to resync your new password with your private npm registry. Youc an do this by:
+You will need to resync your new password with your private npm registry. You can do this by:
+```
+npm login --reg=https://registry.nodejitsu.com
+```
+**If you are using `[email protected]`** you will need to also run login _again_ against your fully qualified registry host:
+```
+npm login --reg=https://<your-subdomain>.registry.nodejitsu.com --always-auth=true
 ```
-$ npm config set registry https://your-subdomain.registry.nodejitsu.com
-$ npm login
+This is because as of `[email protected]` the `npm` CLI now supports multiple registry configurations which both need to be properly configured with your user information.
+
+### How do I publish **new** public modules?
+
+Since all new publishes go by default to your private npm registry when you need **to publish a new public npm package** you must explicitly set the `--reg` flag:
 ```
+npm publish --reg https://registry.npmjs.org
+```
+
+### Can I publish scoped modules to my private npm?
+The short answer is: no, but soon! The long answer is that registering scopes to use with scoped modules is still very nacent and we are approaching this new feature cautioniously to avoid breaking backwards compatibility with any existing customers or clients.
 
-[meta:title]: <> (FAQ)
+[meta:title]: <> (FAQ)
diff --git a/content/npm/index.md b/content/npm/index.md
@@ -1,109 +1,30 @@
-# Hosted Private npm
-
-* [Getting Started](#getting-started)
-* [Web Interface][web-interface]
-	* [User management][user-management]
-	* [Package management][package-management]
-* [Command Line Interface][cli]
+# Nodejitsu private npm
+
+* [Quickstart][quickstart]
+* [Using the `npm` Command Line Interface][cli]
+* [Private npm Web Interface][web-interface]
+  * [User management][user-management]
+  * [Package management][package-management]
+* [`npm` Best Practices][best-practices]
 * [FAQ][faq]
 
 <hr>
 
-## Getting Started
-
-In this getting started guide you will get setup with your Hosted Private npm registry from Nodejitsu as well as learn about some of the best practices for working with `package.json` files.
-
-But first, take a look at this 4 minute introduction to our Private npm solution.
-
-<div style="text-align:center;margin:20px 0;">
-  <iframe src="//player.vimeo.com/video/86596362" width="500" height="281" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
-</div>
-
-### 1. Configure the npm CLI
-
-Just like the public registry, the `npm` CLI program is what you'll use to install, publish and otherwise interact with npm modules. Nodejitsu Enterprise private npm has two changes in the configuration to your npm CLI client:
-
-```
-$ npm config set always-auth true
-$ npm config set strict-ssl true
-$ npm config set ca ""
-```
-
-Why do you need to do these things?
-
-* *Every request requires authentication:* This means that users you have not authorized cannot download packages from your private npm. Since this is not the default behavior of the public npm you need to set:
-
-```
-$ npm config set always-auth true
-```
-
-* *Be strict about SSL*: [We improved our SSL experience](http://blog.nodejitsu.com/improved-ssl-experience-for-private-npm/), now our Private npm registry supports multi-level wildcard certificate issued by [DigiCert](http://www.digiserver.com/) and serves `https://*.registry.nodejitsu.com`, so you'll need to set the following to your npm config:
-
-
-```
-$ npm config set strict-ssl true
-$ npm config set ca ""
-```
-
-### 2. Login & start making requests against your private npm
+Private npm from Nodejitsu is a cloud hosted or on-premise solution for reliably publishing and collaborating on Javascript code for your team. The private modules (or private packages) in your private npm registry are like the production cousin to your private repositories in your private Github (or other DVCS). The private registry offers the same conveience features:
 
-Requests can be made against your private npm in two ways:
+* Secure module distribution with 2048-bit SSL
+* Easy team management from our [web interface][web-interface]
+* Easier module sharing and deployment workflows
+* High reliability with an isolated and replicated npm infrastructure
 
-* _Set the registry for all requests:_ This means that every request will hit your private registry
-```
-  $ npm config set registry https://your-subdomain.registry.nodejitsu.com
-```
-* _Use the `--reg` flag when necessary:_ The `--reg` flag (short for `--registry`) will allow you to make any request against your private registry:
-```
-  $ npm login
-  $ npm info your-private-module --reg http://your-subdomain.registry.nodejitsu.com
-```
-
-**We recommend that **you set the registry for all requests** to avoid any accidental publishes of private modules to the public registry. Since all new publishes go by default to your private npm registry when you need **to publish a new public npm package** you can explicitly set the `--reg` flag:
-
-```
-  $ cd /my/new/public/package
-  $ npm init
-  $ npm publish --reg https://registry.npmjs.org
-```
-
-More information available at the [Command Line Interface Documentation][cli]
-
-
-### 3. Login to the Web Interface
-
-```
-http://your-subdomain.npm.nodejitsu.com
-```
-
-More information available at the [Web Interface Documentation][web-interface]
-
-### PROTIP: Publish modules using `publishConfig`
-
-The `publishConfig` in your package.json does the following (from the [npm documentation](https://github.com/isaacs/npm/blob/master/doc/files/package.json.md#publishconfig)):
-
-> This is a set of config values that will be used at publish-time. It's especially
-> handy if you want to set the tag or registry, so that you can ensure that a given
-> package is not tagged with "latest" or published to the global public registry by default.
->
-> Any config values can be overridden, but of course only "tag" and "registry" probably
-> matter for the purposes of publishing.
-
-For example:
-
-``` js
-  {
-    "publishConfig": { "registry": "https://your-subdomain.registry.nodejitsu.com" }
-  }
-```
-
-The benefits of using `publishConfig` is that it avoids accidental publishes to the public registry due to user error. Take for example a developer on your team who has not properly configured their machine by running `npm config set registry` or using the `--reg` flag. _That command would send your code public._ By using the `publishConfig` property you avoid that because it is part of your application.
+Got it? Great! Why don't you check-out the [Quickstart][quickstart]?
 
+[meta:title]: <> (Hosted Private npm)
 
+[quickstart]: /npm/quickstart
+[best-practices]: /npm/best-practices
 [web-interface]: /npm/web
 [user-management]: /npm/web#user-management
 [package-management]: /npm/web#package-management
 [cli]: /npm/cli
-[faq]: /npm/faq
-
-[meta:title]: <> (Hosted Private npm)
+[faq]: /npm/faq
diff --git a/content/npm/quickstart.md b/content/npm/quickstart.md
@@ -0,0 +1,66 @@
+## Quickstart
+
+This quickstart will get setup with your Hosted Private npm registry from Nodejitsu. But first, if you haven't already take a look at this 4 minute introduction to our private npm registry:
+
+<div style="text-align:center;margin:20px 0;">
+  <iframe src="//player.vimeo.com/video/86596362" width="500" height="281" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
+</div>
+
+For your copy and paste pleasure, all the commands you need to get started on in one place:
+
+```
+npm config set always-auth true
+npm config set ca ""
+npm login --reg https://registry.nodejitsu.com
+npm config set registry https://<your-subdomain>.registry.nodejitsu.com
+```
+
+What exactly is this doing for to your `npm` client? We're glad you asked:
+
+### 1. Configure the npm CLI
+
+Just like the public registry, the `npm` CLI program is what you'll use to install, publish and otherwise interact with npm modules. Nodejitsu Enterprise private npm has two changes in the configuration to your npm CLI client:
+
+```
+npm config set always-auth true
+npm config set ca ""
+```
+
+### 2. Login
+
+To use a private npm from Nodejitsu you need to sync your public npm credentials with us. To do this you simply run:
+```
+npm login --reg=https://registry.nodejitsu.com
+```
+
+**If you are using `[email protected]`** you will need to also run login _again_ against your fully qualified registry host:
+```
+npm login --reg=https://<your-subdomain>.registry.nodejitsu.com --always-auth=true
+```
+This is because as of `[email protected]` the `npm` CLI now supports multiple registry configurations which both need to be properly configured with your user information.
+
+### 3. start making requests against your private npm
+
+We recommend that you set your private npm registry as your default registry for all requests. This ensures that no one accidentally publishes a module publicly.
+```
+  npm config set registry https://your-subdomain.registry.nodejitsu.com
+```
+
+Alternatively, you can _ue the `--reg` flag when necessary._ The `--reg` flag (short for `--registry`) will allow you to make any request against your private registry:
+```
+  npm info your-private-module --reg http://your-subdomain.registry.nodejitsu.com
+```
+
+More information available at the [`npm` Command Line Interface Documentation][cli] and our [FAQ][faq].
+
+### 4. Login to the Web Interface
+
+```
+http://your-subdomain.npm.nodejitsu.com
+```
+
+More information available at the [Private npm Web Interface Documentation][web-interface].
+
+[web-interface]: /npm/web
+[cli]: /npm/cli
+[faq]: /npm/faq