diff --git a/website/i18n/en.json b/website/i18n/en.json index 1645b6e31..386e5df7e 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -57,9 +57,8 @@ "This project is maintained by a dedicated group of people.|statement made to reader": "This project is maintained by a dedicated group of people.", "Learn more about Verdaccio using the [documentation on this site.](/docs/en/installation.html)|no description given": "Learn more about Verdaccio using the [documentation on this site.](/docs/en/installation.html)", "You can follow and contact us on|no description given": "You can follow and contact us on", - "If the documentation is not enough help, you can try browsing into our|no description given": "If the documentation is not enough help, you can try browsing into our", "and also you can chat with the Verdaccio community at|no description given": "and also you can chat with the Verdaccio community at", - "More Help?|no description given": "More Help?", + "If the documentation is not enough help, you can try browsing into our|no description given": "If the documentation is not enough help, you can try browsing into our", "This project is maintained by the Verdaccio community.|no description given": "This project is maintained by the Verdaccio community.", "Get Started|no description given": "Get Started", "Contribute|no description given": "Contribute", diff --git a/website/versioned_docs/version-3.3.0/dev-plugins.md b/website/versioned_docs/version-3.3.0/dev-plugins.md new file mode 100644 index 000000000..2ff51c63d --- /dev/null +++ b/website/versioned_docs/version-3.3.0/dev-plugins.md @@ -0,0 +1,194 @@ +--- +id: version-3.3.0-dev-plugins +title: Developing Plugins +original_id: dev-plugins +--- + +There are many ways to extend `verdaccio`, the kind of plugins supported are: + +* Authentication plugins +* Middleware plugins (since `v2.7.0`) +* Storage plugins since (`v3.x`) + +> We recommend developing plugins using our [flow type definitions](https://github.com/verdaccio/flow-types). + +## Authentication Plugin + +Basically we have to return an object with a single method called `authenticate` that will recieve 3 arguments (`user, password, callback`). + +### API + +```flow +interface IPluginAuth extends IPlugin { + login_url?: string; + authenticate(user: string, password: string, cb: Callback): void; + adduser(user: string, password: string, cb: Callback): void; + allow_access(user: RemoteUser, pkg: $Subtype, cb: Callback): void; + allow_publish(user: RemoteUser, pkg: $Subtype, cb: Callback): void; +} +``` +> Only `adduser`, `allow_access` and `allow_publish` are optional, verdaccio provide a fallback in all those cases. + +#### Callback + +Once the authentication has been executed there is 2 options to give a response to `verdaccio`. + +###### OnError + +Either something bad happened or auth was unsuccessful. + +```flow +callback(null, false) +``` + +###### OnSuccess + +The auth was successful. + + +`groups` is an array of strings where the user is part of. + +``` + callback(null, groups); +``` + +### Example + +```javascript +function Auth(config, stuff) { + var self = Object.create(Auth.prototype); + self._users = {}; + + // config for this module + self._config = config; + + // verdaccio logger + self._logger = stuff.logger; + + // pass verdaccio logger to ldapauth + self._config.client_options.log = stuff.logger; + + return self; +} + +Auth.prototype.authenticate = function (user, password, callback) { + var LdapClient = new LdapAuth(self._config.client_options); + .... + LdapClient.authenticate(user, password, function (err, ldapUser) { + ... + var groups; + ... + callback(null, groups); + }); +}; + +module.exports = Auth; +``` + +And the configuration will looks like: + +```yaml +auth: + htpasswd: + file: ./htpasswd +``` +Where `htpasswd` is the sufix of the plugin name. eg: `verdaccio-htpasswd` and the rest of the body would be the plugin configuration params. + +## Middleware Plugin + +Middleware plugins have the capability to modify the API layer, either adding new endpoints or intercepting requests. + +```flow +interface verdaccio$IPluginMiddleware extends verdaccio$IPlugin { + register_middlewares(app: any, auth: IBasicAuth, storage: IStorageManager): void; +} +``` + +### register_middlewares + +The method provide full access to the authentification and storage via `auth` and `storage`. `app` is the express application that allows you to add new endpoints. + +> A pretty good example +of middleware plugin is the [sinopia-github-oauth](https://github.com/soundtrackyourbrand/sinopia-github-oauth) and [verdaccio-audit](https://github.com/verdaccio/verdaccio-audit). + +### API + +```js +function register_middlewares(expressApp, authInstance, storageInstance) { + /* more stuff */ +} +``` + +To register a middleware we need an object with a single method called `register_middlewares` that will recieve 3 arguments (`expressApp, auth, storage`). +*Auth* is the authentification instance and *storage* is also the main Storage instance that will give you have access to all to the storage actions. + + +## Storage Plugin + +Verdaccio by default uses a file system storage plugin [local-storage](https://github.com/verdaccio/local-storage), but, since `verdaccio@3.x` you can plug in a custom storage replacing the default behaviour. + +### API + +The storage API is a bit more complex, you will need to create a class that return a `IPluginStorage` implementation. Please see details bellow. + +```flow +class LocalDatabase{ + constructor(config: $Subtype, logger: verdaccio$Logger): ILocalData; +} + +interface IPluginStorage { + logger: verdaccio$Logger; + config: $Subtype; + add(name: string, callback: verdaccio$Callback): void; + remove(name: string, callback: verdaccio$Callback): void; + get(callback: verdaccio$Callback): void; + getSecret(): Promise; + setSecret(secret: string): Promise; + getPackageStorage(packageInfo: string): verdaccio$IPackageStorage; + search(onPackage: verdaccio$Callback, onEnd: verdaccio$Callback, validateName: Function): void; +} + +interface IPackageStorageManager { + path: string; + logger: verdaccio$Logger; + writeTarball(name: string): verdaccio$IUploadTarball; + readTarball(name: string): verdaccio$IReadTarball; + readPackage(fileName: string, callback: verdaccio$Callback): void; + createPackage(name: string, value: verdaccio$Package, cb: verdaccio$Callback): void; + deletePackage(fileName: string, callback: verdaccio$Callback): void; + removePackage(callback: verdaccio$Callback): void; + updatePackage(pkgFileName: string, + updateHandler: verdaccio$Callback, + onWrite: verdaccio$Callback, + transformPackage: Function, + onEnd: verdaccio$Callback): void; + savePackage(fileName: string, json: verdaccio$Package, callback: verdaccio$Callback): void; +} + +class verdaccio$IUploadTarball extends stream$PassThrough { + abort: Function; + done: Function; + _transform: Function; + abort(): void; + done(): void; +} + +class verdaccio$IReadTarball extends stream$PassThrough { + abort: Function; + abort(): void; +} +``` + +> The Storage API is still experimental and might change in the next minor versions. For further information about Storage API please follow the [types +definitions in our official repository](https://github.com/verdaccio/flow-types). + +### Storage Plugins Examples + +The following list of plugins are implementing the Storage API and might be used them as example. + +* [verdaccio-memory](https://github.com/verdaccio/verdaccio-memory) +* [local-storage](https://github.com/verdaccio/local-storage) +* [verdaccio-google-cloud](https://github.com/verdaccio/verdaccio-google-cloud) +* [verdaccio-s3-storage](https://github.com/Remitly/verdaccio-s3-storage/tree/s3) + +> Are you willing to contribute with new Storage Plugins? [Click here.](https://github.com/verdaccio/verdaccio/issues/103#issuecomment-357478295) diff --git a/website/versioned_docs/version-3.3.0/install.md b/website/versioned_docs/version-3.3.0/install.md new file mode 100644 index 000000000..a00b93f41 --- /dev/null +++ b/website/versioned_docs/version-3.3.0/install.md @@ -0,0 +1,49 @@ +--- +id: version-3.3.0-installation +title: Installation +original_id: installation +--- + +Verdaccio is a multiplatform web application. To install it, you need a few prerequisites. + +#### Prerequisites + +1. Node higher than + - For version `verdaccio@2.x` Node `v4.6.1` is the minimum supported version. + - For version `verdaccio@latest` Node `6.12.0` is the minimum supported version. +2. npm `>=3.x` or `yarn` +3. The web interface supports the `Chrome, Firefox, Edge, and IE9` browsers. + +## Installing the CLI + +`verdaccio` must be installed globaly using either of the following methods: + +Using `npm` + +```bash +npm install -g verdaccio +``` +or using `yarn` + +```bash +yarn global add verdaccio +``` + +![install verdaccio](/svg/install_verdaccio.gif) + + +## Basic Usage + +Once it has been installed, you only need to execute the CLI command: + +```bash +$> verdaccio +warn --- config file - /home/.config/verdaccio/config.yaml +warn --- http address - http://localhost:4873/ - verdaccio/3.0.1 +``` + +For more information about the CLI, please [read the cli section](cli.md). + +## Docker Image + +`verdaccio` has an official docker image you can use, and in most cases, the default configuration is good enough. For more information about how to install the official image, [read the docker section](docker.md). diff --git a/website/versioned_docs/version-3.3.0/plugins.md b/website/versioned_docs/version-3.3.0/plugins.md new file mode 100644 index 000000000..8ef411ebc --- /dev/null +++ b/website/versioned_docs/version-3.3.0/plugins.md @@ -0,0 +1,146 @@ +--- +id: version-3.3.0-plugins +title: Plugins +original_id: plugins +--- + +Verdaccio is an plugabble aplication. It can be extended in many ways, either new authentication methods, adding +endpoints or using a custom storage. + +> If you are interested to develop your own plugin, read the [development](dev-plugins.md) section. + +## Usage + +### Installation + +```bash +$> npm install --global verdaccio-activedirectory +``` +`verdaccio` as a sinopia fork it has backward compability with plugins that are compatible with `sinopia@1.4.0`. In such case the installation is the same. + +``` +$> npm install --global sinopia-memory +``` + +### Configuration + +Open the `config.yaml` file and update the `auth` section as follows: + +The default configuration looks like this, due we use a build-in `htpasswd` plugin by default that you can disable just commenting out the following lines. + + +### Auth Plugin Configuration + +```yaml + htpasswd: + file: ./htpasswd + #max_users: 1000 +``` + +and replacing them with (in case you decide to use a `ldap` plugin. + +```yaml +auth: + activedirectory: + url: "ldap://10.0.100.1" + baseDN: 'dc=sample,dc=local' + domainSuffix: 'sample.local' +``` + +#### Multiple Auth plugins + +This is tecnically possible, the plugins order becames important, the the credentials will resolved in order. + +```yaml +auth: + htpasswd: + file: ./htpasswd + #max_users: 1000 + activedirectory: + url: "ldap://10.0.100.1" + baseDN: 'dc=sample,dc=local' + domainSuffix: 'sample.local' +``` + +### Middleware Plugin Configuration + +This is an example how to set up a middleware plugin. All middleware plugins must be defined in the **middlewares** namespace. + +```yaml +middlewares: + audit: + enabled: true +``` + +> You might follow the [audit middle plugin](https://github.com/verdaccio/verdaccio-audit) as base example. + +### Store Plugin Configuration + +This is an example how to set up a storage plugin. All storage plugins must be defined in the **store** namespace. + +```yaml +store: + memory: + limit: 1000 +``` + +> If you define a custom store, the property **storage** in the configuration file will be ignored. + +## Legacy plugins + +### Sinopia Plugins + +(compatible all versions) + +* [sinopia-npm](https://www.npmjs.com/package/sinopia-npm): auth plugin for sinopia supporting an npm registry. +* [sinopia-memory](https://www.npmjs.com/package/sinopia-memory): auth plugin for sinopia that keeps users in memory. +* [sinopia-github-oauth-cli](https://www.npmjs.com/package/sinopia-github-oauth-cli). +* [sinopia-crowd](https://www.npmjs.com/package/sinopia-crowd): auth plugin for sinopia supporting atlassian crowd. +* [sinopia-activedirectory](https://www.npmjs.com/package/sinopia-activedirectory): Active Directory authentication plugin for sinopia. +* [sinopia-github-oauth](https://www.npmjs.com/package/sinopia-github-oauth): authentication plugin for sinopia2, supporting github oauth web flow. +* [sinopia-delegated-auth](https://www.npmjs.com/package/sinopia-delegated-auth): Sinopia authentication plugin that delegates authentication to another HTTP URL +* [sinopia-altldap](https://www.npmjs.com/package/sinopia-altldap): Alternate LDAP Auth plugin for Sinopia +* [sinopia-request](https://www.npmjs.com/package/sinopia-request): An easy and fully auth-plugin with configuration to use an external API. +* [sinopia-htaccess-gpg-email](https://www.npmjs.com/package/sinopia-htaccess-gpg-email): Generate password in htaccess format, encrypt with GPG and send via MailGun API to users. +* [sinopia-mongodb](https://www.npmjs.com/package/sinopia-mongodb): An easy and fully auth-plugin with configuration to use a mongodb database. +* [sinopia-htpasswd](https://www.npmjs.com/package/sinopia-htpasswd): auth plugin for sinopia supporting htpasswd format. +* [sinopia-leveldb](https://www.npmjs.com/package/sinopia-leveldb): a leveldb backed auth plugin for sinopia private npm. +* [sinopia-gitlabheres](https://www.npmjs.com/package/sinopia-gitlabheres): Gitlab authentication plugin for sinopia. +* [sinopia-gitlab](https://www.npmjs.com/package/sinopia-gitlab): Gitlab authentication plugin for sinopia +* [sinopia-ldap](https://www.npmjs.com/package/sinopia-ldap): LDAP auth plugin for sinopia. +* [sinopia-github-oauth-env](https://www.npmjs.com/package/sinopia-github-oauth-env) Sinopia authentication plugin with github oauth web flow. + +> All sinopia plugins should be compatible with all future verdaccio versions. Anyhow, we encourage contributors to migrate them to the +modern verdaccio API and using the prefix as *verdaccio-xx-name*. + +## Verdaccio Plugins + +(compatible since 2.1.x) + +### Authorization Plugins + +* [verdaccio-bitbucket](https://github.com/idangozlan/verdaccio-bitbucket): Bitbucket authentication plugin for verdaccio. +* [verdaccio-ldap](https://www.npmjs.com/package/verdaccio-ldap): LDAP auth plugin for verdaccio. +* [verdaccio-active-directory](https://github.com/nowhammies/verdaccio-activedirectory): Active Directory authentication plugin for verdaccio +* [verdaccio-gitlab](https://github.com/bufferoverflow/verdaccio-gitlab): use GitLab Personal Access Token to authenticate +* [verdaccio-htpasswd](https://github.com/verdaccio/verdaccio-htpasswd): Auth based on htpasswd file plugin (built-in) for verdaccio +* [verdaccio-github-oauth](https://github.com/aroundus-inc/verdaccio-github-oauth): Github oauth authentication plugin for verdaccio. + +### Middleware Plugins + +* [verdaccio-audit](https://github.com/verdaccio/verdaccio-audit): verdaccio plugin for *npm audit* cli support (built-in) (compatible since 3.x) + +* [verdaccio-profile-api](https://github.com/ahoracek/verdaccio-profile-api): verdacci plugin for *npm profile* cli support and *npm profile set password* for *verdaccio-htpasswd* based authentificaton + +### Storage Plugins + +(compatible since 3.x) + +* [verdaccio-memory](https://github.com/verdaccio/verdaccio-memory) Storage plugin to host packages in Memory +* [verdaccio-s3-storage](https://github.com/remitly/verdaccio-s3-storage) Storage plugin to host packages **Amazon S3** +* [verdaccio-google-cloud](https://github.com/verdaccio/verdaccio-google-cloud) Storage plugin to host packages **Google Cloud Storage** + +## Caveats + +> Not all these plugins are been tested continuously, some of them might not work at all. +Please if you found any issue feel free to notify the owner of each plugin. diff --git a/website/versioned_docs/version-3.3.0/web.md b/website/versioned_docs/version-3.3.0/web.md new file mode 100644 index 000000000..6de482fca --- /dev/null +++ b/website/versioned_docs/version-3.3.0/web.md @@ -0,0 +1,26 @@ +--- +id: version-3.3.0-webui +title: Web User Interface2 +original_id: webui +--- + +

+ +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 +``` + +All access restrictions defined to [protect your packages](protect-your-dependencies.md) will also apply to the Web Interface. + +### Configuration + +Property | Type | Required | Example | Support | Description +--- | --- | --- | --- | --- | --- +enable | boolean | No | true/false | all | allow to display the web interface +title | string | No | Verdaccio | all | HTML head title description +logo | string | No | http://my.logo.domain/logo.png | all | a URI where logo is located diff --git a/website/versions.json b/website/versions.json index 29a315a80..1e6d74043 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,3 +1,4 @@ [ + "3.3.0", "3.2.0" ]