Merge pull request #236 from verdaccio/fix_105

Increase Documentation

wiki/README.md

@@ -9,15 +9,16 @@ from a fresh look at the code and the outstanding issues. So here we are 🎉
 ## Getting Started
 
 <!---
-* [Command Line](cli.md)
 * [Understand the configuration file](config.md)
 -->
+* [Command Line](cli.md)
 * [Setting up *uplinks*](uplinks.md)
-<!---
 * [Packages Access](packages.md)
+* [Enable Notifications](notifications.md)
+<!---
 * [Logs](logs.md)
 * [Configure the Web](web.md)
-* [Enable Notifications](notifications.md)
+
 * [Understand the storage](storage.md)
 * [Authorization and access](auth.md)
 * [Installing Plugins](plugins.md)

wiki/cli.md

@@ -0,0 +1,30 @@
+# Command Line Interface
+
+The verdaccio CLI is your go start the application. 
+
+
+## Installation
+
+Please make sure latest Node 4 LTS and NPM 3+ are installed.
+
+Then, install the CLI globally (you may need sudo):
+
+```bash
+$ npm install -g verdaccio
+```
+or if you use `yarn`
+
+```bash
+$ yarn add global verdaccio
+```
+
+## Commands
+
+```bash
+$ verdaccio --listen 4000 --config ./config.yaml
+```
+
+Command | Default | Example | Description 
+--- | --- | --- | --- 
+--listen \ **-l** | 4873 |  -p 7000 | http port
+--config \ **-c** | ~/home/user/.local/verdaccio/config.yaml | /foo/bar/config.yaml | the configuration file

wiki/notifications.md

@@ -0,0 +1,55 @@
+# Notifications
+
+
+Notify was built primarily to use with Slack's Incoming
+webhooks, but will also deliver a simple payload to
+any endpoint. Currently only active for `publish` / `create`
+commands.
+
+## Usage
+
+An example with a **hipchat** hook:
+
+#### Single notification
+
+```yaml
+notify:
+  method: POST
+  headers: [{'Content-Type': 'application/json'}]
+  endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
+  content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'
+```
+
+#### Multiple notification
+
+```yaml
+notify:
+  'example-package-1'
+     method: POST
+     headers: [{'Content-Type': 'application/json'}]
+     endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
+     content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'
+  'example-package-2'
+     method: POST
+     headers: [{'Content-Type': 'application/json'}]
+     endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
+     content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'
+  'example-package-3'
+     method: POST
+     headers: [{'Content-Type': 'application/json'}]
+     endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
+     content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'
+     
+
+```
+
+## Configuration
+
+Property | Type | Required | Support | Description 
+--- | --- | --- | --- | --- 
+method| string | No | all | HTTP verb
+packagePattern| string | No | all | Only run this notification if the package name matches the regular
+headers| array/object | Yes | all | If this endpoint requires specific headers, set them here as an array of key: value objects.
+endpoint| string | Yes | all | set the URL endpoint for this call
+content| string | Yes | all | any Handlebar expressions  
+

wiki/packages.md

@@ -0,0 +1,114 @@
+# Package Access
+
+It's a series of contrains that allow or restrict access to the local storage based in specific criteria.
+
+The security constraints remains on shoulders of the plugin being used, by default `verdaccio` uses the `htpasswd` plugin. If you use a different plugin the behaviour might be different. The default plugin `htpasswd` does not handles by itself `allow_access` and `allow_publish`, it's use an internal fallback in case the plugin is not ready for it. For more information about permissions visit [the authentification section in the wiki](auth.md).
+
+### Usage
+
+```yalm
+packages:
+  # scoped packages
+  '@scope/*':
+    allow_access: all
+    allow_publish: all
+    proxy: server2
+
+  'private-*':
+    access: all
+    publish: all
+    proxy_access: uplink1
+
+  '**':
+    # allow all users (including non-authenticated users) to read and
+    # publish all packages
+    allow_access: all
+    allow_publish: all
+    proxy_access: uplink2
+```
+if none is specified, the default one remains
+
+```yaml
+packages:
+  '**':
+     access: all
+     publish: $authenticated
+```
+
+The list of valid groups according the default plugins are
+
+```js
+'$all', '$anonymous', '@all', '@anonymous', 'all', 'undefined', 'anonymous'
+```
+All users recieves all those set of permissions independently of is anonymous or not plus the groups provided by the plugin, in case of `htpasswd` return the username as a group. For instance, if you are logged as `npmUser` the list of groups will be.
+
+```js
+// groups without '$' are going to be deprecated eventually
+'$all', '$anonymous', '@all', '@anonymous', 'all', 'undefined', 'anonymous', 'npmUser'
+```
+
+If you want to protect specific set packages under your group, you need todo something like this. Let's use a `Regex` that covers all prefixed `npmuser-` packages. We recomend use a prefix for your packages, in that way it'd be easier to protect them.
+
+```yaml
+packages:
+  'npmuser-*':
+     access: npmuser
+     publish: npmuser
+```
+
+Restart `verdaccio` and in your console try to install `npmuser-core`.
+
+```bash
+$ npm install npmuser-core
+npm install npmuser-core
+npm ERR! code E403
+npm ERR! 403 Forbidden: npmuser-core@latest
+
+npm ERR! A complete log of this run can be found in:
+npm ERR!     /Users/user/.npm/_logs/2017-07-02T12_20_14_834Z-debug.log
+```
+You can change the existing behaviour using a different plugin authentication. `verdaccio` just check whether the user that try to access or publish specific package belongs to the right group.
+
+#### Set multiple groups
+
+Define multiple access groups is fairly easy, just define them with a white space between them.
+
+```yaml
+  'company-*':
+    allow_access: admin internal
+    allow_publish: admin
+    proxy_access: server1
+  'supersecret-*':
+    allow_access: secret super-secret-area ultra-secret-area
+    allow_publish: secret ultra-secret-area
+    proxy_access: server1
+    
+```
+
+#### Blocking access to set of packages
+
+If you want to block the acccess/publish to a specific group of packages. Just, do not define `access` and `publish`.
+
+```yaml
+packages:
+  'old-*':
+  '**':
+     access: all
+     publish: $authenticated
+```
+
+### Configuration
+
+You can define mutiple `packages` and each of them must have an unique `Regex`.
+
+Property | Type | Required | Example | Support | Description 
+--- | --- | --- | --- | --- | --- 
+allow_access/access | string | No | $all | all | define groups allowed to access the package
+allow_publish/publish | string | No | $authenticated | all | define groups allowed to publish
+proxy_access/proxy | string | No |npmjs | all | limit look ups for specific uplink 
+storage | boolean | No | [true,false] | all | TODO
+
+
+
+
+

wiki/uplinks.md

@@ -1,6 +1,8 @@
 # Uplinks
 
 An *upnlink* is a link with an external registry that provides acccess to external packages. 
+
+### Usage
  
 ```yaml
 uplinks: