Merge pull request #308 from verdaccio/feature_wiki_upgrade

docs: Add new sections to documentation
2025-04-08 02:54:13 -05:00 · 2017-08-29 20:09:48 +02:00 · 2017-08-29 20:09:48 +02:00 · 0582e05edc
commit 0582e05edc
parent c30555c699 54dbf115ba
8 changed files with 288 additions and 31 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -12,6 +12,7 @@ There are many ways to contribute to the Verdaccio Project. Here’s a list of t
 * [Reporting a Bug](CONTRIBUTING.md#reporting-a-bug)
 * [Request Features](CONTRIBUTING.md#request-features)
 * [Plugins](CONTRIBUTING.md#plugins)
+* [Improve the Documentation](wiki/README.md)

 Please read carefully this document. It will guide you to provide maintainers and readers valuable information to boots the process solve the issue or evaluate your proposal.

--- a/README.md
+++ b/README.md
@ -40,6 +40,8 @@ See in detail each of these [use cases](https://github.com/verdaccio/verdaccio/t

 ## Get Started

+**Help? Don't miss the [documentation section](wiki/README.md)**
+
 ### Prerequisites

 * Node.js >= 4.6.1
@ -221,6 +223,7 @@ About the storage there is a running discussion [here](https://github.com/verdac

 If you have any issue you can try the following options, do no desist to ask or check our issues database, perhaps someone has asked already what you are looking for.

+* [Documentation](wiki/README.md)
 * [Most common questions](https://github.com/verdaccio/verdaccio/issues?q=is%3Aissue+is%3Aopen+label%3Aquestion)
 * [Reporting a bug](https://github.com/verdaccio/verdaccio/blob/master/CONTRIBUTING.md#reporting-a-bug)
 * [Running discussions](https://github.com/verdaccio/verdaccio/issues?q=is%3Aissue+is%3Aopen+label%3Adiscuss)
--- a/wiki/README.md
+++ b/wiki/README.md
@ -1,32 +1,51 @@
-# Welcome to the verdaccio wiki!

-`verdaccio` is a fork of `sinopia`.

-It appeared that sinopia maintenance had stalled and the author had abandoned it,
+`verdaccio` is a fork of **sinopia** and it's backwards compatible.
+
+🚀🚨🚨🚨🚨 **<--- Here we will have a fancy logo soon -->** 🚨🚨🚨🚨🚀
+
+You can vote 👍🏻👍🏻👍🏻 or contribute in [this thread](https://github.com/verdaccio/verdaccio/issues/237).
+
+## Why should I use verdaccio?👌
+
+
+* I am/was **sinopia** user and need an **easy migration**.
+* I need a lightweight and free solution 🎉 to host my private packages and no license worries 🎊.
+* I need long-term support and help when I got stuck.
+* I want a product compatible with the newer tools as **Yarn** and **DevOps (Docker, Ansible, Puppet, etc)** tools.
+* An evolving plugabble product, not only for **Authentification**, also for **Storage** and more in the future.
+* An active community 🙋‍♂️🙋.
+* Integration with **Nexus**, **Artifactoy** and any other npm compatible registry.
+
+A bunch more of reasons [you might be interested](https://medium.com/@jotadeveloper/five-use-cases-where-a-npm-private-proxy-fits-in-your-workflow-632a81779c14).
+
+### Why we forked from Sinopia? 🚀
+
+It [appeared that sinopia maintenance had stalled and the author had abandoned it](https://github.com/rlidwka/sinopia/issues/376),
 so there was a suggestion that the sinopia-using community would benefit
-from a fresh look at the code and the outstanding issues. So here we are 🎉🎉🎉.
+from a fresh look at the code and the outstanding issues. So here we are 🎉🎉🎉.  The last step about the [detach from sinopia](https://github.com/verdaccio/verdaccio/issues/38).
+
+### Near Future 🚧
+
+`verdaccio` aims to be compatible with sinopia along the time preserving the main features, a lightweight app based on local file system and easy installation but being able to be pluggable and built over a modern tool stack.
+

 ## Getting Started

-<!---
-* [Understand the configuration file](config.md)
-->
+* [Installation](install.md)
 * [Command Line](cli.md)
+* [Understand the configuration file](config.md)
 * [Setting up *uplinks*](uplinks.md)
 * [Packages Access](packages.md)
 * [Enable Notifications](notifications.md)
-* [Installing Plugins](plugins.md)
 * [Authorization and access](auth.md)
-<!---
-* [Logs](logs.md)
+* [Logs](logger.md)
 * [Configure the Web](web.md)

-* [Understand the storage](storage.md)
-->
-
 ## Advanced Configurations

 * [SSL Certificates](ssl.md)
+* [Installing Plugins](plugins.md)

 ## Servers

@ -42,3 +61,7 @@ from a fresh look at the code and the outstanding issues. So here we are 🎉

 * [Ansible](ansible.md)
 * [Docker](docker.md)
+
+## Recipes
+
+* [Learn how to protect your packages](recipes/protect-your-dependencies.md)
--- a/wiki/cli.md
+++ b/wiki/cli.md
@ -2,24 +2,6 @@

 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
-```
-
-> Warning: Verdaccio current is not support PM2's cluster mode, run it with cluster mode may cause unknown behavior
-
 ## Commands

 ```bash
--- a/wiki/config.md
+++ b/wiki/config.md
@ -0,0 +1,165 @@
+# Configuration File
+
+This file is the cornerstone of verdaccio where you can modify the default behaviour, enable plugins and extend features.
+
+A default configuration file is created the very first time you run `verdaccio`.
+
+## Default Configuration
+
+The default configuration has support for **scoped** packages and allow any user to access all packages but only **authenticated users to publish**.
+
+```yaml
+storage: ./storage
+auth:
+  htpasswd:
+    file: ./htpasswd
+uplinks:
+  npmjs:
+    url: https://registry.npmjs.org/
+packages:
+  '@*/*':
+    access: $all
+    publish: $authenticated
+    proxy: npmjs
+  '**':
+    proxy: npmjs
+logs:
+  - {type: stdout, format: pretty, level: http}
+```
+
+## Sections
+
+The following sections explain what means each property and the different otpions
+
+### Storage
+
+Is the location of the default storage. **Verdaccio is by default based on local file system**.
+
+```yaml
+storage: ./storage
+```
+
+### Authentification
+
+The authentification set up is done here, the default auth is based on `htpasswd` and is build-in. You can modify this behaviour via [plugins](plugins.md). For more information about this section read the [auth page](auth.md).
+
+```yaml
+auth:
+  htpasswd:
+    file: ./htpasswd
+    max_users: 1000
+```
+
+### Web UI
+
+This properties allow you to modify the look and feel of the web UI. For more information about this section read the [web ui page](web.md).
+
+```yaml
+web:
+  enable: true
+  title: Verdaccio
+  logo: logo.png
+```
+
+### Upkinks
+
+Uplinks is the ability of the system to fetch packages from remote registries when those packages are not available locally. For more information about this section read the [uplinks page](uplinks.md).
+
+
+```yaml
+uplinks:
+  npmjs:
+    url: https://registry.npmjs.org/
+```
+
+### Packages
+
+Packages allow the user how the packages are gonna be accessed. For more information about this section read the [packages page](packages.md).
+
+
+```yaml
+packages:
+  '@*/*':
+    access: $all
+    publish: $authenticated
+    proxy: npmjs
+```
+
+## Advanced Settings
+
+### Offline Publish 
+
+By default `verdaccio` does not allow to publish when the client is offline, that behavior can be overridden set it in to *true*.
+
+```yaml
+publish:
+  allow_offline: false
+```
+
+Since: *v2.3.6* due [#223](https://github.com/verdaccio/verdaccio/pull/223)
+
+### URL Prefix
+
+```yaml
+url_prefix: https://dev.company.local/verdaccio/
+```
+
+Since: *v2.3.6* due [#197](https://github.com/verdaccio/verdaccio/pull/197)
+
+
+### Max Body Size
+
+By default the maximum body size for a JSON document is `1mb`, if you run in errors as `"request entity too large"` you may increase this value.
+
+```yaml
+max_body_size: 1mb
+```
+
+### Listen Port
+
+`verdaccio` runs by default in the port `4873`. Change the port can be done via [cli](cli.md) or in the configuration file, the following options are valid.
+
+```yaml
+listen:
+# - localhost:4873            # default value
+# - http://localhost:4873     # same thing
+# - 0.0.0.0:4873              # listen on all addresses (INADDR_ANY)
+# - https://example.org:4873  # if you want to use https
+# - [::1]:4873                # ipv6
+# - unix:/tmp/verdaccio.sock    # unix socket
+```
+
+### HTTPS
+
+To enable `https` in `verdaccio` enough with set your `listen` domain with the protocol *https://*. For more information about this section read the [ssl page](ssl.md).
+
+
+```yaml
+https:
+  key: path/to/server.key
+  cert: path/to/server.crt
+  ca: path/to/server.pem
+```
+
+### Notifications
+
+Enable notifications to three party tools is fairly easy via web hooks. For more information about this section read the [notifications page](notifications.md).
+
+```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"}'
+```
+
+
+
+
+
+
+
+
+
+
+ 
--- a/wiki/install.md
+++ b/wiki/install.md
@ -0,0 +1,44 @@
+# Installation
+
+Verdaccio is a multiplatform web application, to install you need at least some prerequisites.
+
+#### Prerequisites
+
+* Node higher than **4.6.1**
+* npm or yarn
+
+
+## Installing the CLI
+
+`Verdaccio` must be install globaly using any of the most modern
+
+Using `npm` 
+
+```bash
+npm install -g npm
+
+```
+or using `yarn` 
+
+```bash
+yarn global add verdaccio
+
+```
+
+> Warning: Verdaccio current is not support PM2's cluster mode, run it with cluster mode may cause unknown behavior
+
+## Basic Usage
+
+Once has been installed you only need to execute the CLI command.
+
+```bash
+$> verdaccio
+```
+
+![](https://cdn-images-1.medium.com/max/720/1*jDHnZ7_68u5s1lFK2cygnA.gif)
+
+For more information about CLI please [read the cli section](cli.md).
+
+## Docker Image
+
+`verdaccio` has a official docker image you can use, in the most of cases is good enough just the default configuration, for more information about how to install the official image [read the docker section](docker.md).
--- a/wiki/logger.md
+++ b/wiki/logger.md
@ -0,0 +1,20 @@
+# Logger
+
+As any web application, verdaccio has a customisable built-in logger. You can define multiple types of outputs.
+
+```yaml
+logs:
+  # console output
+  - {type: stdout, format: pretty, level: http}
+  # file output
+  - {type: file, path: verdaccio.log, level: info}
+```
+
+### Configuration
+
+Property | Type | Required | Example | Support | Description 
+--- | --- | --- | --- | --- | --- 
+type |  string | No | [stdout, file] | all | define the output
+path | string | No | verdaccio.log | all | if type is file, define the location of that file 
+format | string | No | [pretty, pretty-timestamped] | all | output format
+level | string | No | [fatal, error, warn, http, info, debug, trace] | all | verbose level
--- a/wiki/web.md
+++ b/wiki/web.md
@ -0,0 +1,19 @@
+# Web UI
+
+Verdaccio has a web user interface to display only the private packges and can be customisable.
+
+```yaml
+web:
+  enable: true
+  title: Verdaccio
+  logo: logo.png
+```
+  
+
+### Configuration
+
+Property | Type | Required | Example | Support | Description 
+--- | --- | --- | --- | --- | --- 
+enable | boolean | No | true/false | all | allow to display the web interface
+title | string | No | $authenticated | all | HTML head title description
+logo | string | No | http://my.logo.domain/logo.png | all | a URI where logo is located