Infrastructure/verdaccio
0
Fork 0
mirror of https://github.com/verdaccio/verdaccio.git synced 2025-04-01 02:42:23 -05:00
Code Issues Activity

chore: prepare releaser website 3.3.0

Browse source
This commit is contained in:
Juan Picado @jotadeveloper 2018-07-22 20:25:40 +02:00
parent b82b8f12a3
commit 7bff7e91e5
No known key found for this signature in database
GPG key ID: 18AC54485952D158
6 changed files with 417 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
website/i18n/en.json
View file

@ -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",

194
website/versioned_docs/version-3.3.0/dev-plugins.md Normal file
View file

@ -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<PackageAccess>, cb: Callback): void;
allow_publish(user: RemoteUser, pkg: $Subtype<PackageAccess>, 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<IPluginStorage>{
constructor(config: $Subtype<verdaccio$Config>, logger: verdaccio$Logger): ILocalData;
}
interface IPluginStorage {
logger: verdaccio$Logger;
config: $Subtype<verdaccio$Config>;
add(name: string, callback: verdaccio$Callback): void;
remove(name: string, callback: verdaccio$Callback): void;
get(callback: verdaccio$Callback): void;
getSecret(): Promise<string>;
setSecret(secret: string): Promise<any>;
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)

49
website/versioned_docs/version-3.3.0/install.md Normal file
View file

@ -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).

146
website/versioned_docs/version-3.3.0/plugins.md Normal file
View file

@ -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.

26
website/versioned_docs/version-3.3.0/web.md Normal file
View file

@ -0,0 +1,26 @@
---
id: version-3.3.0-webui
title: Web User Interface2
original_id: webui
---
<p align="center"><img src="https://github.com/verdaccio/verdaccio/blob/master/assets/gif/verdaccio_big_30.gif?raw=true"></p>
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

1
website/versions.json
View file

@ -1,3 +1,4 @@
[
"3.3.0",
"3.2.0"
]