Infrastructure/verdaccio
0
Fork 0
mirror of https://github.com/verdaccio/verdaccio.git synced 2024-12-30 22:34:10 -05:00
Code Issues Activity

docs: small improvements

Browse source
This commit is contained in:
Juan Picado @jotadeveloper 2018-07-22 20:23:53 +02:00
parent 1536b97d0b
commit b82b8f12a3
No known key found for this signature in database
GPG key ID: 18AC54485952D158
4 changed files with 62 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
docs/dev-plugins.md
View file

@ -3,29 +3,44 @@ id: dev-plugins
title: "Developing Plugins" title: "Developing Plugins"
--- ---
There are many ways to extend `verdaccio`, currently we support `authentication plugins`, `middleware plugins` (since `v2.7.0`) and `storage plugins` since (`v3.x`). 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 ## Authentication Plugin
This section will describe how it looks like a Verdaccio plugin in a ES5 way. Basically we have to return an object with a single method called `authenticate` that will recieve 3 arguments (`user, password, callback`). Once the authentication has been executed there is 2 options to give a response to `verdaccio`. Basically we have to return an object with a single method called `authenticate` that will recieve 3 arguments (`user, password, callback`).
### API ### API
```js ```flow
function authenticate (user, password, callback) { interface IPluginAuth extends IPlugin {
...more stuff 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.
##### OnError #### 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. Either something bad happened or auth was unsuccessful.
``` ```flow
callback(null, false) callback(null, false)
``` ```
##### OnSuccess ###### OnSuccess
The auth was successful. The auth was successful.
@ -69,7 +84,7 @@ Auth.prototype.authenticate = function (user, password, callback) {
module.exports = Auth; module.exports = Auth;
``` ```
And the setup And the configuration will looks like:
```yaml ```yaml
auth: auth:
@ -81,7 +96,17 @@ Where `htpasswd` is the sufix of the plugin name. eg: `verdaccio-htpasswd` and t
## Middleware Plugin ## Middleware Plugin
Middleware plugins have the capability to modify the API layer, either adding new endpoints or intercepting requests. 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 > 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). of middleware plugin is the [sinopia-github-oauth](https://github.com/soundtrackyourbrand/sinopia-github-oauth) and [verdaccio-audit](https://github.com/verdaccio/verdaccio-audit).
@ -99,28 +124,32 @@ To register a middleware we need an object with a single method called `register
## Storage Plugin ## 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. 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 ### API
The storage API is a bit more complex, you will need to create a class that return a `ILocalData` implementation. Please see details bellow. The storage API is a bit more complex, you will need to create a class that return a `IPluginStorage` implementation. Please see details bellow.
```js ```flow
class LocalDatabase<IPluginStorage>{
class LocalDatabase<ILocalData>{ constructor(config: $Subtype<verdaccio$Config>, logger: verdaccio$Logger): ILocalData;
constructor(config: Config, logger: Logger): ILocalData;
} }
declare interface verdaccio$ILocalData { interface IPluginStorage {
logger: verdaccio$Logger;
config: $Subtype<verdaccio$Config>;
add(name: string, callback: verdaccio$Callback): void; add(name: string, callback: verdaccio$Callback): void;
remove(name: string, callback: verdaccio$Callback): void; remove(name: string, callback: verdaccio$Callback): void;
get(callback: verdaccio$Callback): void; get(callback: verdaccio$Callback): void;
getSecret(): Promise<string>; getSecret(): Promise<string>;
setSecret(secret: string): Promise<any>; setSecret(secret: string): Promise<any>;
getPackageStorage(packageInfo: string): verdaccio$IPackageStorage; getPackageStorage(packageInfo: string): verdaccio$IPackageStorage;
search(onPackage: verdaccio$Callback, onEnd: verdaccio$Callback, validateName: Function): void;
} }
declare interface verdaccio$ILocalPackageManager { interface IPackageStorageManager {
path: string;
logger: verdaccio$Logger;
writeTarball(name: string): verdaccio$IUploadTarball; writeTarball(name: string): verdaccio$IUploadTarball;
readTarball(name: string): verdaccio$IReadTarball; readTarball(name: string): verdaccio$IReadTarball;
readPackage(fileName: string, callback: verdaccio$Callback): void; readPackage(fileName: string, callback: verdaccio$Callback): void;
@ -135,14 +164,17 @@ declare interface verdaccio$ILocalPackageManager {
savePackage(fileName: string, json: verdaccio$Package, callback: verdaccio$Callback): void; savePackage(fileName: string, json: verdaccio$Package, callback: verdaccio$Callback): void;
} }
interface IUploadTarball extends stream$PassThrough { class verdaccio$IUploadTarball extends stream$PassThrough {
abort: Function;
done: Function;
_transform: Function;
abort(): void; abort(): void;
done(): void; done(): void;
} }
interface IReadTarball extends stream$PassThrough { class verdaccio$IReadTarball extends stream$PassThrough {
abort: Function;
abort(): void; abort(): void;
done(): void;
} }
``` ```

2
docs/install.md
View file

@ -41,8 +41,6 @@ warn --- config file - /home/.config/verdaccio/config.yaml
warn --- http address - http://localhost:4873/ - verdaccio/3.0.1 warn --- http address - http://localhost:4873/ - verdaccio/3.0.1
``` ```
![](https://cdn-images-1.medium.com/max/720/1*jDHnZ7_68u5s1lFK2cygnA.gif)
For more information about the CLI, please [read the cli section](cli.md). For more information about the CLI, please [read the cli section](cli.md).
## Docker Image ## Docker Image

12
docs/plugins.md
View file

@ -3,9 +3,9 @@ id: plugins
title: "Plugins" title: "Plugins"
--- ---
Verdaccio is an plugabble aplication. It can be extended in many ways, either new authentication methods, adding Verdaccio is an plugabble aplication. It can be extended in many ways, either new authentication methods, adding
endpoints or using a custom storage. endpoints or using a custom storage.
> If you are interested to develop your own plugin, read the [development](dev-plugins.md) section. > If you are interested to develop your own plugin, read the [development](dev-plugins.md) section.
## Usage ## Usage
@ -26,8 +26,8 @@ $> npm install --global sinopia-memory
Open the `config.yaml` file and update the `auth` section as follows: 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. 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 ### Auth Plugin Configuration
```yaml ```yaml
@ -71,6 +71,8 @@ middlewares:
enabled: true enabled: true
``` ```
> You might follow the [audit middle plugin](https://github.com/verdaccio/verdaccio-audit) as base example.
### Store Plugin Configuration ### Store Plugin Configuration
This is an example how to set up a storage plugin. All storage plugins must be defined in the **store** namespace. This is an example how to set up a storage plugin. All storage plugins must be defined in the **store** namespace.
@ -139,5 +141,5 @@ modern verdaccio API and using the prefix as *verdaccio-xx-name*.
## Caveats ## Caveats
> Not all these plugins are been tested continuously, some of them might not work at all. > 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. Please if you found any issue feel free to notify the owner of each plugin.

4
docs/web.md
View file

@ -1,9 +1,9 @@
--- ---
id: webui id: webui
title: "Web User Interface" title: "Web User Interface2"
--- ---
<p align="center"><img src="https://firebasestorage.googleapis.com/v0/b/jotadeveloper-website.appspot.com/o/verdaccio_long_video2.gif?alt=media&token=4d20cad1-f700-4803-be14-4b641c651b41"></p> <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. Verdaccio has a web user interface to display only the private packges and can be customisable.