class LocalDatabase
verdaccio@3.0.0
+
`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
diff --git a/website/translated_docs/de/contributing.md b/website/translated_docs/de/contributing.md
index 1a0e2a901..8631f61ba 100644
--- a/website/translated_docs/de/contributing.md
+++ b/website/translated_docs/de/contributing.md
@@ -8,8 +8,7 @@ First of all Jumping into an unfamiliar code base is not easy but we are here to
If you are willing for asking, we use two channels for discussions:
-* [Public Gitter channel](https://gitter.im/verdaccio/)
-* [Contributors Slack channel](https://verdaccio-npm.slack.com) (unfortunately only by email invitation, you might ask in **Gitter** to be included)
+* [Public Discord channel](http://chat.verdaccio.org/)
## Getting started
diff --git a/website/translated_docs/de/dev-plugins.md b/website/translated_docs/de/dev-plugins.md
index df7e87632..384ba171a 100644
--- a/website/translated_docs/de/dev-plugins.md
+++ b/website/translated_docs/de/dev-plugins.md
@@ -2,28 +2,45 @@
id: dev-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
-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
-```js
-function authenticate (user, password, callback) {
- ...more stuff
+```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: $Subtypeclass LocalDatabase
verdaccio@3.0.0
+
`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
diff --git a/website/translated_docs/fr/contributing.md b/website/translated_docs/fr/contributing.md
index 1a0e2a901..8631f61ba 100644
--- a/website/translated_docs/fr/contributing.md
+++ b/website/translated_docs/fr/contributing.md
@@ -8,8 +8,7 @@ First of all Jumping into an unfamiliar code base is not easy but we are here to
If you are willing for asking, we use two channels for discussions:
-* [Public Gitter channel](https://gitter.im/verdaccio/)
-* [Contributors Slack channel](https://verdaccio-npm.slack.com) (unfortunately only by email invitation, you might ask in **Gitter** to be included)
+* [Public Discord channel](http://chat.verdaccio.org/)
## Getting started
diff --git a/website/translated_docs/fr/dev-plugins.md b/website/translated_docs/fr/dev-plugins.md
index df7e87632..384ba171a 100644
--- a/website/translated_docs/fr/dev-plugins.md
+++ b/website/translated_docs/fr/dev-plugins.md
@@ -2,28 +2,45 @@
id: dev-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
-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
-```js
-function authenticate (user, password, callback) {
- ...more stuff
+```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: $Subtypeclass LocalDatabase
verdaccio@2.3.6 due #223
+
+### URL Prefix
+
+```yaml
+url_prefix: https://dev.company.local/verdaccio/
+```
+
+Since: `verdaccio@2.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 `10mb`, if you run in errors as `"request entity too large"` you may increase this value.
+
+```yaml
+max_body_size: 10mb
+```
+
+### Listen Port
+
+`verdaccio` runs by default in the port `4873`. Changing 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` it's enough to set the `listen` flag with the protocol *https://*. For more information about this section read the [ssl page](ssl.md).
+
+```yaml
+https:
+ key: ./path/verdaccio-key.pem
+ cert: ./path/verdaccio-cert.pem
+ ca: ./path/verdaccio-csr.pem
+```
+
+### Proxy
+
+Proxies are special-purpose HTTP servers designed to transfer data from remote servers to local clients.
+
+#### http_proxy and https_proxy
+
+If you have a proxy in your network you can set a `X-Forwarded-For` header using the following properties.
+
+```yaml
+http_proxy: http://something.local/
+https_proxy: https://something.local/
+```
+
+#### no_proxy
+
+This variable should contain a comma-separated list of domain extensions proxy should not be used for.
+
+```yaml
+no_proxy: localhost,127.0.0.1
+```
+
+### Notifications
+
+Enabling notifications to third-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"}'
+```
+
+> For more detailed configuration settings, please [check the source code](https://github.com/verdaccio/verdaccio/tree/master/conf).
+
+### Audit
+
+Since: verdaccio@3.0.0
+
+`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
+
+> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
+
+```yaml
+middlewares:
+ audit:
+ enabled: true
+```
\ No newline at end of file
diff --git a/website/translated_docs/it/contributing.md b/website/translated_docs/it/contributing.md
new file mode 100644
index 000000000..8631f61ba
--- /dev/null
+++ b/website/translated_docs/it/contributing.md
@@ -0,0 +1,80 @@
+---
+id: contributing
+title: "Contributing Verdaccio"
+---
+First of all Jumping into an unfamiliar code base is not easy but we are here to help you.
+
+## Comunication Channels
+
+If you are willing for asking, we use two channels for discussions:
+
+* [Public Discord channel](http://chat.verdaccio.org/)
+
+## Getting started
+
+As a first glance verdaccio is a single repository, but there are many ways you might contribute and a variety of technologies to practice.
+
+### Finding my spot
+
+All we have different skills, so, let's see where you might feel comfortable.
+
+### I know or I want to learn Node.js
+
+Node.js is the base of `verdaccio`, we use libraries as `express`, `commander`, `request` or `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`.
+
+We have a long [list of plugins](plugins.md) ready to be used and improved but at the same time [you might create your own](dev-plugins.md).
+
+### I would prefer to work in the User Interface
+
+Recently we have moved to modern techonologies as `React` and `element-react`. We are looking forward to see new ideas how to improve the UI.
+
+### I feel more confortable improving the stack
+
+Of course, we will be happy to help us improving the stack, you can upgrade dependencies as `eslint`, `stylelint`, `webpack`. You migt merely improve the `webpack` configuration would be great. Any suggestion is very welcome. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
+
+Here some ideas:
+
+* Create a common eslint rules to be used across all dependencies or plugins
+* Improve Flow types definitions delivery
+* Moving to Webpack 4
+* Improve hot reload with Webpack
+* We use babel and webpack across all dependencies, why not a common preset?
+* Improve continous integration delivery
+
+### I do great Documentation
+
+Many contributors find typos and grammar issues, that also helps to improve the overall experience for troubleshooting.
+
+### I am a Designer
+
+We have a frontend website 
+
+We have setup a project where you can choose your favourite language, if you do not find your language feel free to request one [creating a ticket](https://github.com/verdaccio/verdaccio/issues/new).
+
+[Go to Crowdin Verdaccio](https://crowdin.com/project/verdaccio)
+
+## I'm ready to contribute
+
+If you are thinking *"I've seen already the [repositories](repositories.md) and I'm willing to start right away"* then I have good news for you, that's the next step.
+
+You will need learn how to build, [we have prepared a guide just for that](build.md).
+
+Once you have played around with all scripts and you know how to use them, we are ready to go to the next step, run the [**Unit Test**](test.md).
+
+## Full list of contributors. We want to see your face here !
+
+
diff --git a/website/translated_docs/it/dev-plugins.md b/website/translated_docs/it/dev-plugins.md
new file mode 100644
index 000000000..384ba171a
--- /dev/null
+++ b/website/translated_docs/it/dev-plugins.md
@@ -0,0 +1,188 @@
+---
+id: dev-plugins
+title: "Developing 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
+ 
+
+
+To pull the latest pre-built [docker image](https://hub.docker.com/r/verdaccio/verdaccio/):
+
+```bash
+docker pull verdaccio/verdaccio
+```
+
+
+
+## Tagged Versions
+
+Since version `v2.x` you can pull docker images by [tag](https://hub.docker.com/r/verdaccio/verdaccio/tags/), as follows:
+
+For a major version:
+
+```bash
+docker pull verdaccio/verdaccio:3
+```
+
+For a minor version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0
+```
+
+For a specific (patch) version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0.1
+```
+
+For the next major release using the `beta` (master branch) version.
+
+```bash
+docker pull verdaccio/verdaccio:beta
+```
+
+> If you are interested on a list of tags, [please visit the Docker Hub website](https://hub.docker.com/r/verdaccio/verdaccio/tags/).
+
+## Running verdaccio using Docker
+
+To run the docker container:
+
+```bash
+docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
+```
+
+The last argument defines which image to use. The above line will pull the latest prebuilt image from dockerhub, if you haven't done that already.
+
+If you have [build an image locally](#build-your-own-docker-image) use `verdaccio` as the last argument.
+
+You can use `-v` to bind mount `conf`, `storage` and `plugins` to the hosts filesystem:
+
+```bash
+V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio -p 4873:4873 \
+ -v $V_PATH/conf:/verdaccio/conf \
+ -v $V_PATH/storage:/verdaccio/storage \
+ -v $V_PATH/plugins:/verdaccio/plugins \
+ verdaccio/verdaccio
+```
+
+> Note: Verdaccio runs as a non-root user (uid=100, gid=101) inside the container, if you use bind mount to override default, you need to make sure the mount directory is assigned to the right user. In above example, you need to run `sudo chown -R 100:101 /opt/verdaccio` otherwise you will get permission errors at runtime. [Use docker volume](https://docs.docker.com/storage/volumes/) is recommended over using bind mount.
+
+### Plugins
+
+Plugins can be installed in a separate directory and mounted using Docker or Kubernetes, however make sure you build plugins with native dependencies using the same base image as the Verdaccio Dockerfile.
+
+### Docker and custom port configuration
+
+Any `host:port` configured in `conf/config.yaml` under `listen` is currently ignored when using docker.
+
+If you want to reach verdaccio docker instance under different port, lets say `5000` in your `docker run` command replace `-p 4873:4873` with `-p 5000:4873`.
+
+In case you need to specify which port to listen to **in the docker container**, since version 2.?.? you can do so by providing additional arguments to `docker run`: `--env PORT=5000` This changes which port the docker container exposes and the port verdaccio listens to.
+
+Of course the numbers you give to `-p` paremeter need to match, so assuming you want them to all be the same this is what you could copy, paste and adopt:
+
+```bash
+PORT=5000; docker run -it --rm --name verdaccio \
+ --env PORT -p $PORT:$PORT
+ verdaccio/verdaccio
+```
+
+### Using HTTPS with Docker
+
+You can configure the protocol verdaccio is going to listen on, similarly to the port configuration. You have to overwrite the default value("http") of the `PROTOCOL` environment variable to "https", after you specified the certificates in the config.yaml.
+
+```bash
+PROTOCOL=https; docker run -it --rm --name verdaccio \
+ --env PROTOCOL -p 4873:4873
+ verdaccio/verdaccio
+```
+
+### Using docker-compose
+
+1. Get the latest version of [docker-compose](https://github.com/docker/compose).
+2. Build and run the container:
+
+```bash
+$ docker-compose up --build
+```
+
+You can set the port to use (for both container and host) by prefixing the above command with `PORT=5000`.
+
+Docker will generate a named volume in which to store persistent application data. You can use `docker inspect` or `docker volume inspect` to reveal the physical location of the volume and edit the configuration, such as:
+
+ $ docker volume inspect verdaccio_verdaccio
+ [
+ {
+ "Name": "verdaccio_verdaccio",
+ "Driver": "local",
+ "Mountpoint": "/var/lib/docker/volumes/verdaccio_verdaccio/_data",
+ "Labels": null,
+ "Scope": "local"
+ }
+ ]
+
+
+
+## Build your own Docker image
+
+```bash
+docker build -t verdaccio .
+```
+
+There is also an npm script for building the docker image, so you can also do:
+
+```bash
+npm run build:docker
+```
+
+Note: The first build takes some minutes to build because it needs to run `npm install`, and it will take that long again whenever you change any file that is not listed in `.dockerignore`.
+
+If you want to use the docker image on a rpi or a compatible device there is also a dockerfile available. To build the docker image for raspberry pi execute:
+
+```bash
+npm run build:docker:rpi
+```
+
+Please note that for any of the above docker commands you need to have docker installed on your machine and the docker executable should be available on your `$PATH`.
+
+## Docker Examples
+
+There is a separate repository that hosts multiple configurations to compose Docker images with `verdaccio`, for instance, as reverse proxy:
+
+Alternatively, if you have a certificate as `server.pfx` format, you can add the following configuration section. The passphrase is optional and only needed, if your certificate is encrypted. + + + +https: pfx: /Users/user/.config/verdaccio/server.pfx passphrase: 'secret' ```` + +More info on the `key`, `cert`, `ca`, `pfx` and `passphrase` arguments on the [Node documentation](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) + +* Run `verdaccio` in your command line. + +* Open the browser and load `https://your.domain.com:port/` + +This instructions are mostly valid under OSX and Linux, on Windows the paths will vary but, the steps are the same. + +## Docker + +If you are using the Docker image, you have to set the `PROTOCOL` environment variable to `https` as the `listen` argument is provided on the [Dockerfile](https://github.com/verdaccio/verdaccio/blob/master/Dockerfile#L43), and thus ignored from your config file. + +You can also set the `PORT` environment variable if you are using a different port than `4873`. \ No newline at end of file diff --git a/website/translated_docs/it/test.md b/website/translated_docs/it/test.md new file mode 100644 index 000000000..818cefa16 --- /dev/null +++ b/website/translated_docs/it/test.md @@ -0,0 +1,134 @@ +--- +id: unit-testing +title: "Unit Testing" +--- +All tests are split in three folders: + +- `test/unit` - Tests that cover functions that transform data in an non-trivial way. These tests simply `require()` a few files and run code in there, so they are very fast. +- `test/functional` - Tests that launch a verdaccio instance and perform a series of requests to it over http. They are slower than unit tests. +- `test/integration` - Tests that launch a verdaccio instance and do requests to it using npm. They are really slow and can hit a real npm registry. **unmaintained test** + +Unit and functional tests are executed automatically by running `npm test` from the project's root directory. Integration tests are supposed to be executed manually from time to time. + +We use `jest` for all test. + +## The npm Script + +To run the test script you can use either `npm` or `yarn`. + + yarn run test + + +That will trigger only two first groups of test, unit and functional. + +### Using test/unit + +The following is just an example how a unit test should looks like. Basically follow the `jest` standard. + +Try to describe what exactly does the unit test in a single sentence in the header of the `test` section. + +```javacript +const verdaccio = require('../../src/api/index'); +const config = require('./partials/config'); + +describe('basic system test', () => { + + beforeAll(function(done) { + // something important + }); + + afterAll((done) => { + // undo something important + }); + + test('server should respond on /', done => { + // your test + done(); + }); +}); +``` + +### Using test/functional + +Funtional testing in verdaccio has a bit more of complextity that needs a deep explanation in order to success in your experience. + +All starts in the `index.js` file. Let's dive in into it. + +```javascript +// we create 3 server instances + const config1 = new VerdaccioConfig( + './store/test-storage', + './store/config-1.yaml', + 'http://localhost:55551/'); + const config2 = new VerdaccioConfig( + './store/test-storage2', + './store/config-2.yaml', + 'http://localhost:55552/'); + const config3 = new VerdaccioConfig( + './store/test-storage3', + './store/config-3.yaml', + 'http://localhost:55553/'); + const server1: IServerBridge = new Server(config1.domainPath); + const server2: IServerBridge = new Server(config2.domainPath); + const server3: IServerBridge = new Server(config3.domainPath); + const process1: IServerProcess = new VerdaccioProcess(config1, server1, SILENCE_LOG); + const process2: IServerProcess = new VerdaccioProcess(config2, server2, SILENCE_LOG); + const process3: IServerProcess = new VerdaccioProcess(config3, server3, SILENCE_LOG); + const express: any = new ExpressServer(); + ... + + // we check whether all instances has been started, since run in independent processes + beforeAll((done) => { + Promise.all([ + process1.init(), + process2.init(), + process3.init()]).then((forks) => { + _.map(forks, (fork) => { + processRunning.push(fork[0]); + }); + express.start(EXPRESS_PORT).then((app) =>{ + done(); + }, (err) => { + done(err); + }); + }).catch((error) => { + done(error); + }); + }); + + // after finish all, we ensure are been stoped + afterAll(() => { + _.map(processRunning, (fork) => { + fork.stop(); + }); + express.server.close(); + }); + + +``` + +### Usage + +Here we are gonna describe how it looks like an usual functional test, check inline for more detail information. + +#### The lib/server.js + +The server class is just a wrapper that simulates a `npm` client and provides a simple API for the funtional test. + +As we mention in the previous section, we are creating 3 process servers that are accessible in each process as `server1`, `server2` and ``server3`. + +Using such reference you will be able to send request to any of the 3 instance running. + +```javascript +
export default function(server) { + // we recieve any server instance via arguments + test('add tag - 404', () => { + // we interact with the server instance. + return server.addTag('testpkg-tag', 'tagtagtag', '0.0.1').status(404).body_error(/no such package/); + }); +}); +``` + +### Test/integration + +These section never has been used, but we are looking for help to make it run properly. **All new ideas are very welcome.** \ No newline at end of file diff --git a/website/translated_docs/it/uplinks.md b/website/translated_docs/it/uplinks.md new file mode 100644 index 000000000..7d0076b7d --- /dev/null +++ b/website/translated_docs/it/uplinks.md @@ -0,0 +1,86 @@ +--- +id: uplinks +title: "Uplinks" +--- +An *uplink* is a link with an external registry that provides acccess to external packages. + + + +### Usage + +```yaml +uplinks: + npmjs: + url: https://registry.npmjs.org/ + server2: + url: http://mirror.local.net/ + timeout: 100ms + server3: + url: http://mirror2.local.net:9000/ + baduplink: + url: http://localhost:55666/ +``` + +### Configuration + +You can define mutiple uplinks and each of them must have an unique name (key). They can have two properties: + +| Property | Type | Required | Example | Support | Description | Default | +| ------------ | ------- | -------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | +| url | string | Yes | https://registry.npmjs.org/ | all | The registry url | npmjs | +| ca | string | No | ~./ssl/client.crt' | all | SSL path certificate | No default | +| timeout | string | No | 100ms | all | set new timeout for the request | 30s | +| maxage | string | No | 10m | all | limit maximun failure request | 2m | +| fail_timeout | string | No | 10m | all | defines max time when a request becomes a failure | 5m | +| max_fails | number | No | 2 | all | limit maximun failure request | 2 | +| cache | boolean | No | [true,false] | >= 2.1 | cache all remote tarballs in storage | true | +| auth | list | No | [see below](uplinks.md#auth-property) | >= 2.5 | assigns the header 'Authorization' [more info](http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules) | disabled | +| headers | list | No | authorization: "Bearer SecretJWToken==" | all | list of custom headers for the uplink | disabled | +| strict_ssl | boolean | No | [true,false] | >= 3.0 | If true, requires SSL certificates be valid. | true | + +#### Auth property + +The `auth` property allows you to use an auth token with an uplink. Using the default environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: true # defaults to `process.env['NPM_TOKEN']` +``` + +or via a specified environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: FOO_TOKEN +``` + +`token_env: FOO_TOKEN`internally will use `process.env['FOO_TOKEN']` + +or by directly specifying a token: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token: "token" +``` + +> Note: `token` has priority over `token_env` + +### You Must know + +* Verdaccio does not use Basic Authentication since version `v2.3.0`. All tokens generated by verdaccio are based on JWT ([JSON Web Token](https://jwt.io/)) +* Uplinks must be registries compatible with the `npm` endpoints. Eg: *verdaccio*, `sinopia@1.4.0`, *npmjs registry*, *yarn registry*, *JFrog*, *Nexus* and more. +* Setting `cache` to false will help to save space in your hard drive. This will avoid store `tarballs` but [it will keep metadata in folders](https://github.com/verdaccio/verdaccio/issues/391). +* Exceed with multiple uplinks might slow down the lookup of your packages due for each request a npm client does, verdaccio does 1 call for each uplink. +* The (timeout, maxage and fail_timeout) format follow the [NGINX measurement units](http://nginx.org/en/docs/syntax.html) \ No newline at end of file diff --git a/website/translated_docs/it/use-cases.md b/website/translated_docs/it/use-cases.md new file mode 100644 index 000000000..969dc9195 --- /dev/null +++ b/website/translated_docs/it/use-cases.md @@ -0,0 +1,31 @@ +--- +id: use-cases +title: "Use Cases" +--- +## Using private packages + +You can add users and manage which users can access which packages. + +It is recommended that you define a prefix for your private packages, for example "local", so all your private things will look like this: `local-foo`. This way you can clearly separate public packages from private ones. + +## Using public packages from npmjs.org + +If some package doesn't exist in the storage, server will try to fetch it from npmjs.org. If npmjs.org is down, it serves packages from cache pretending that no other packages exist. Verdaccio will download only what's needed (= requested by clients), and this information will be cached, so if client will ask the same thing second time, it can be served without asking npmjs.org for it. + +Example: if you successfully request express@3.0.1 from this server once, you'll able to do that again (with all it's dependencies) anytime even if npmjs.org is down. But say express@3.0.0 will not be downloaded until it's actually needed by somebody. And if npmjs.org is offline, this server would say that only express@3.0.1 (= only what's in the cache) is published, but nothing else. + +## Override public packages + +If you want to use a modified version of some public package `foo`, you can just publish it to your local server, so when your type `npm install foo`, it'll consider installing your version. + +There's two options here: + +1. You want to create a separate fork and stop synchronizing with public version. + + If you want to do that, you should modify your configuration file so verdaccio won't make requests regarding this package to npmjs anymore. Add a separate entry for this package to *config.yaml* and remove `npmjs` from `proxy` list and restart the server. + + When you publish your package locally, you should probably start with version string higher than existing one, so it won't conflict with existing package in the cache. + +2. You want to temporarily use your version, but return to public one as soon as it's updated. + + In order to avoid version conflicts, you should use a custom pre-release suffix of the next patch version. For example, if a public package has version 0.1.2, you can upload 0.1.3-my-temp-fix. This way your package will be used until its original maintainer updates his public package to 0.1.3. \ No newline at end of file diff --git a/website/translated_docs/it/web.md b/website/translated_docs/it/web.md new file mode 100644 index 000000000..77216c021 --- /dev/null +++ b/website/translated_docs/it/web.md @@ -0,0 +1,28 @@ +--- +id: webui +title: "Web User Interface2" +--- + + +
verdaccio@3.0.0
+
`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
diff --git a/website/translated_docs/ja/contributing.md b/website/translated_docs/ja/contributing.md
index 1a0e2a901..8631f61ba 100644
--- a/website/translated_docs/ja/contributing.md
+++ b/website/translated_docs/ja/contributing.md
@@ -8,8 +8,7 @@ First of all Jumping into an unfamiliar code base is not easy but we are here to
If you are willing for asking, we use two channels for discussions:
-* [Public Gitter channel](https://gitter.im/verdaccio/)
-* [Contributors Slack channel](https://verdaccio-npm.slack.com) (unfortunately only by email invitation, you might ask in **Gitter** to be included)
+* [Public Discord channel](http://chat.verdaccio.org/)
## Getting started
diff --git a/website/translated_docs/ja/dev-plugins.md b/website/translated_docs/ja/dev-plugins.md
index df7e87632..384ba171a 100644
--- a/website/translated_docs/ja/dev-plugins.md
+++ b/website/translated_docs/ja/dev-plugins.md
@@ -2,28 +2,45 @@
id: dev-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
-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
-```js
-function authenticate (user, password, callback) {
- ...more stuff
+```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: $Subtypeclass LocalDatabase
verdaccio@2.3.6 due #223
+
+### URL Prefix
+
+```yaml
+url_prefix: https://dev.company.local/verdaccio/
+```
+
+Since: `verdaccio@2.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 `10mb`, if you run in errors as `"request entity too large"` you may increase this value.
+
+```yaml
+max_body_size: 10mb
+```
+
+### Listen Port
+
+`verdaccio` runs by default in the port `4873`. Changing 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` it's enough to set the `listen` flag with the protocol *https://*. For more information about this section read the [ssl page](ssl.md).
+
+```yaml
+https:
+ key: ./path/verdaccio-key.pem
+ cert: ./path/verdaccio-cert.pem
+ ca: ./path/verdaccio-csr.pem
+```
+
+### Proxy
+
+Proxies are special-purpose HTTP servers designed to transfer data from remote servers to local clients.
+
+#### http_proxy and https_proxy
+
+If you have a proxy in your network you can set a `X-Forwarded-For` header using the following properties.
+
+```yaml
+http_proxy: http://something.local/
+https_proxy: https://something.local/
+```
+
+#### no_proxy
+
+This variable should contain a comma-separated list of domain extensions proxy should not be used for.
+
+```yaml
+no_proxy: localhost,127.0.0.1
+```
+
+### Notifications
+
+Enabling notifications to third-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"}'
+```
+
+> For more detailed configuration settings, please [check the source code](https://github.com/verdaccio/verdaccio/tree/master/conf).
+
+### Audit
+
+Since: verdaccio@3.0.0
+
+`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
+
+> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
+
+```yaml
+middlewares:
+ audit:
+ enabled: true
+```
\ No newline at end of file
diff --git a/website/translated_docs/ko/contributing.md b/website/translated_docs/ko/contributing.md
new file mode 100644
index 000000000..8631f61ba
--- /dev/null
+++ b/website/translated_docs/ko/contributing.md
@@ -0,0 +1,80 @@
+---
+id: contributing
+title: "Contributing Verdaccio"
+---
+First of all Jumping into an unfamiliar code base is not easy but we are here to help you.
+
+## Comunication Channels
+
+If you are willing for asking, we use two channels for discussions:
+
+* [Public Discord channel](http://chat.verdaccio.org/)
+
+## Getting started
+
+As a first glance verdaccio is a single repository, but there are many ways you might contribute and a variety of technologies to practice.
+
+### Finding my spot
+
+All we have different skills, so, let's see where you might feel comfortable.
+
+### I know or I want to learn Node.js
+
+Node.js is the base of `verdaccio`, we use libraries as `express`, `commander`, `request` or `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`.
+
+We have a long [list of plugins](plugins.md) ready to be used and improved but at the same time [you might create your own](dev-plugins.md).
+
+### I would prefer to work in the User Interface
+
+Recently we have moved to modern techonologies as `React` and `element-react`. We are looking forward to see new ideas how to improve the UI.
+
+### I feel more confortable improving the stack
+
+Of course, we will be happy to help us improving the stack, you can upgrade dependencies as `eslint`, `stylelint`, `webpack`. You migt merely improve the `webpack` configuration would be great. Any suggestion is very welcome. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
+
+Here some ideas:
+
+* Create a common eslint rules to be used across all dependencies or plugins
+* Improve Flow types definitions delivery
+* Moving to Webpack 4
+* Improve hot reload with Webpack
+* We use babel and webpack across all dependencies, why not a common preset?
+* Improve continous integration delivery
+
+### I do great Documentation
+
+Many contributors find typos and grammar issues, that also helps to improve the overall experience for troubleshooting.
+
+### I am a Designer
+
+We have a frontend website
+
+We have setup a project where you can choose your favourite language, if you do not find your language feel free to request one [creating a ticket](https://github.com/verdaccio/verdaccio/issues/new).
+
+[Go to Crowdin Verdaccio](https://crowdin.com/project/verdaccio)
+
+## I'm ready to contribute
+
+If you are thinking *"I've seen already the [repositories](repositories.md) and I'm willing to start right away"* then I have good news for you, that's the next step.
+
+You will need learn how to build, [we have prepared a guide just for that](build.md).
+
+Once you have played around with all scripts and you know how to use them, we are ready to go to the next step, run the [**Unit Test**](test.md).
+
+## Full list of contributors. We want to see your face here !
+
+
diff --git a/website/translated_docs/ko/dev-plugins.md b/website/translated_docs/ko/dev-plugins.md
new file mode 100644
index 000000000..384ba171a
--- /dev/null
+++ b/website/translated_docs/ko/dev-plugins.md
@@ -0,0 +1,188 @@
+---
+id: dev-plugins
+title: "Developing 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
+ 
+
+
+To pull the latest pre-built [docker image](https://hub.docker.com/r/verdaccio/verdaccio/):
+
+```bash
+docker pull verdaccio/verdaccio
+```
+
+
+
+## Tagged Versions
+
+Since version `v2.x` you can pull docker images by [tag](https://hub.docker.com/r/verdaccio/verdaccio/tags/), as follows:
+
+For a major version:
+
+```bash
+docker pull verdaccio/verdaccio:3
+```
+
+For a minor version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0
+```
+
+For a specific (patch) version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0.1
+```
+
+For the next major release using the `beta` (master branch) version.
+
+```bash
+docker pull verdaccio/verdaccio:beta
+```
+
+> If you are interested on a list of tags, [please visit the Docker Hub website](https://hub.docker.com/r/verdaccio/verdaccio/tags/).
+
+## Running verdaccio using Docker
+
+To run the docker container:
+
+```bash
+docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
+```
+
+The last argument defines which image to use. The above line will pull the latest prebuilt image from dockerhub, if you haven't done that already.
+
+If you have [build an image locally](#build-your-own-docker-image) use `verdaccio` as the last argument.
+
+You can use `-v` to bind mount `conf`, `storage` and `plugins` to the hosts filesystem:
+
+```bash
+V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio -p 4873:4873 \
+ -v $V_PATH/conf:/verdaccio/conf \
+ -v $V_PATH/storage:/verdaccio/storage \
+ -v $V_PATH/plugins:/verdaccio/plugins \
+ verdaccio/verdaccio
+```
+
+> Note: Verdaccio runs as a non-root user (uid=100, gid=101) inside the container, if you use bind mount to override default, you need to make sure the mount directory is assigned to the right user. In above example, you need to run `sudo chown -R 100:101 /opt/verdaccio` otherwise you will get permission errors at runtime. [Use docker volume](https://docs.docker.com/storage/volumes/) is recommended over using bind mount.
+
+### Plugins
+
+Plugins can be installed in a separate directory and mounted using Docker or Kubernetes, however make sure you build plugins with native dependencies using the same base image as the Verdaccio Dockerfile.
+
+### Docker and custom port configuration
+
+Any `host:port` configured in `conf/config.yaml` under `listen` is currently ignored when using docker.
+
+If you want to reach verdaccio docker instance under different port, lets say `5000` in your `docker run` command replace `-p 4873:4873` with `-p 5000:4873`.
+
+In case you need to specify which port to listen to **in the docker container**, since version 2.?.? you can do so by providing additional arguments to `docker run`: `--env PORT=5000` This changes which port the docker container exposes and the port verdaccio listens to.
+
+Of course the numbers you give to `-p` paremeter need to match, so assuming you want them to all be the same this is what you could copy, paste and adopt:
+
+```bash
+PORT=5000; docker run -it --rm --name verdaccio \
+ --env PORT -p $PORT:$PORT
+ verdaccio/verdaccio
+```
+
+### Using HTTPS with Docker
+
+You can configure the protocol verdaccio is going to listen on, similarly to the port configuration. You have to overwrite the default value("http") of the `PROTOCOL` environment variable to "https", after you specified the certificates in the config.yaml.
+
+```bash
+PROTOCOL=https; docker run -it --rm --name verdaccio \
+ --env PROTOCOL -p 4873:4873
+ verdaccio/verdaccio
+```
+
+### Using docker-compose
+
+1. Get the latest version of [docker-compose](https://github.com/docker/compose).
+2. Build and run the container:
+
+```bash
+$ docker-compose up --build
+```
+
+You can set the port to use (for both container and host) by prefixing the above command with `PORT=5000`.
+
+Docker will generate a named volume in which to store persistent application data. You can use `docker inspect` or `docker volume inspect` to reveal the physical location of the volume and edit the configuration, such as:
+
+ $ docker volume inspect verdaccio_verdaccio
+ [
+ {
+ "Name": "verdaccio_verdaccio",
+ "Driver": "local",
+ "Mountpoint": "/var/lib/docker/volumes/verdaccio_verdaccio/_data",
+ "Labels": null,
+ "Scope": "local"
+ }
+ ]
+
+
+
+## Build your own Docker image
+
+```bash
+docker build -t verdaccio .
+```
+
+There is also an npm script for building the docker image, so you can also do:
+
+```bash
+npm run build:docker
+```
+
+Note: The first build takes some minutes to build because it needs to run `npm install`, and it will take that long again whenever you change any file that is not listed in `.dockerignore`.
+
+If you want to use the docker image on a rpi or a compatible device there is also a dockerfile available. To build the docker image for raspberry pi execute:
+
+```bash
+npm run build:docker:rpi
+```
+
+Please note that for any of the above docker commands you need to have docker installed on your machine and the docker executable should be available on your `$PATH`.
+
+## Docker Examples
+
+There is a separate repository that hosts multiple configurations to compose Docker images with `verdaccio`, for instance, as reverse proxy:
+
+Alternatively, if you have a certificate as `server.pfx` format, you can add the following configuration section. The passphrase is optional and only needed, if your certificate is encrypted. + + + +https: pfx: /Users/user/.config/verdaccio/server.pfx passphrase: 'secret' ```` + +More info on the `key`, `cert`, `ca`, `pfx` and `passphrase` arguments on the [Node documentation](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) + +* Run `verdaccio` in your command line. + +* Open the browser and load `https://your.domain.com:port/` + +This instructions are mostly valid under OSX and Linux, on Windows the paths will vary but, the steps are the same. + +## Docker + +If you are using the Docker image, you have to set the `PROTOCOL` environment variable to `https` as the `listen` argument is provided on the [Dockerfile](https://github.com/verdaccio/verdaccio/blob/master/Dockerfile#L43), and thus ignored from your config file. + +You can also set the `PORT` environment variable if you are using a different port than `4873`. \ No newline at end of file diff --git a/website/translated_docs/ko/test.md b/website/translated_docs/ko/test.md new file mode 100644 index 000000000..818cefa16 --- /dev/null +++ b/website/translated_docs/ko/test.md @@ -0,0 +1,134 @@ +--- +id: unit-testing +title: "Unit Testing" +--- +All tests are split in three folders: + +- `test/unit` - Tests that cover functions that transform data in an non-trivial way. These tests simply `require()` a few files and run code in there, so they are very fast. +- `test/functional` - Tests that launch a verdaccio instance and perform a series of requests to it over http. They are slower than unit tests. +- `test/integration` - Tests that launch a verdaccio instance and do requests to it using npm. They are really slow and can hit a real npm registry. **unmaintained test** + +Unit and functional tests are executed automatically by running `npm test` from the project's root directory. Integration tests are supposed to be executed manually from time to time. + +We use `jest` for all test. + +## The npm Script + +To run the test script you can use either `npm` or `yarn`. + + yarn run test + + +That will trigger only two first groups of test, unit and functional. + +### Using test/unit + +The following is just an example how a unit test should looks like. Basically follow the `jest` standard. + +Try to describe what exactly does the unit test in a single sentence in the header of the `test` section. + +```javacript +const verdaccio = require('../../src/api/index'); +const config = require('./partials/config'); + +describe('basic system test', () => { + + beforeAll(function(done) { + // something important + }); + + afterAll((done) => { + // undo something important + }); + + test('server should respond on /', done => { + // your test + done(); + }); +}); +``` + +### Using test/functional + +Funtional testing in verdaccio has a bit more of complextity that needs a deep explanation in order to success in your experience. + +All starts in the `index.js` file. Let's dive in into it. + +```javascript +// we create 3 server instances + const config1 = new VerdaccioConfig( + './store/test-storage', + './store/config-1.yaml', + 'http://localhost:55551/'); + const config2 = new VerdaccioConfig( + './store/test-storage2', + './store/config-2.yaml', + 'http://localhost:55552/'); + const config3 = new VerdaccioConfig( + './store/test-storage3', + './store/config-3.yaml', + 'http://localhost:55553/'); + const server1: IServerBridge = new Server(config1.domainPath); + const server2: IServerBridge = new Server(config2.domainPath); + const server3: IServerBridge = new Server(config3.domainPath); + const process1: IServerProcess = new VerdaccioProcess(config1, server1, SILENCE_LOG); + const process2: IServerProcess = new VerdaccioProcess(config2, server2, SILENCE_LOG); + const process3: IServerProcess = new VerdaccioProcess(config3, server3, SILENCE_LOG); + const express: any = new ExpressServer(); + ... + + // we check whether all instances has been started, since run in independent processes + beforeAll((done) => { + Promise.all([ + process1.init(), + process2.init(), + process3.init()]).then((forks) => { + _.map(forks, (fork) => { + processRunning.push(fork[0]); + }); + express.start(EXPRESS_PORT).then((app) =>{ + done(); + }, (err) => { + done(err); + }); + }).catch((error) => { + done(error); + }); + }); + + // after finish all, we ensure are been stoped + afterAll(() => { + _.map(processRunning, (fork) => { + fork.stop(); + }); + express.server.close(); + }); + + +``` + +### Usage + +Here we are gonna describe how it looks like an usual functional test, check inline for more detail information. + +#### The lib/server.js + +The server class is just a wrapper that simulates a `npm` client and provides a simple API for the funtional test. + +As we mention in the previous section, we are creating 3 process servers that are accessible in each process as `server1`, `server2` and ``server3`. + +Using such reference you will be able to send request to any of the 3 instance running. + +```javascript +
export default function(server) { + // we recieve any server instance via arguments + test('add tag - 404', () => { + // we interact with the server instance. + return server.addTag('testpkg-tag', 'tagtagtag', '0.0.1').status(404).body_error(/no such package/); + }); +}); +``` + +### Test/integration + +These section never has been used, but we are looking for help to make it run properly. **All new ideas are very welcome.** \ No newline at end of file diff --git a/website/translated_docs/ko/uplinks.md b/website/translated_docs/ko/uplinks.md new file mode 100644 index 000000000..7d0076b7d --- /dev/null +++ b/website/translated_docs/ko/uplinks.md @@ -0,0 +1,86 @@ +--- +id: uplinks +title: "Uplinks" +--- +An *uplink* is a link with an external registry that provides acccess to external packages. + + + +### Usage + +```yaml +uplinks: + npmjs: + url: https://registry.npmjs.org/ + server2: + url: http://mirror.local.net/ + timeout: 100ms + server3: + url: http://mirror2.local.net:9000/ + baduplink: + url: http://localhost:55666/ +``` + +### Configuration + +You can define mutiple uplinks and each of them must have an unique name (key). They can have two properties: + +| Property | Type | Required | Example | Support | Description | Default | +| ------------ | ------- | -------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | +| url | string | Yes | https://registry.npmjs.org/ | all | The registry url | npmjs | +| ca | string | No | ~./ssl/client.crt' | all | SSL path certificate | No default | +| timeout | string | No | 100ms | all | set new timeout for the request | 30s | +| maxage | string | No | 10m | all | limit maximun failure request | 2m | +| fail_timeout | string | No | 10m | all | defines max time when a request becomes a failure | 5m | +| max_fails | number | No | 2 | all | limit maximun failure request | 2 | +| cache | boolean | No | [true,false] | >= 2.1 | cache all remote tarballs in storage | true | +| auth | list | No | [see below](uplinks.md#auth-property) | >= 2.5 | assigns the header 'Authorization' [more info](http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules) | disabled | +| headers | list | No | authorization: "Bearer SecretJWToken==" | all | list of custom headers for the uplink | disabled | +| strict_ssl | boolean | No | [true,false] | >= 3.0 | If true, requires SSL certificates be valid. | true | + +#### Auth property + +The `auth` property allows you to use an auth token with an uplink. Using the default environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: true # defaults to `process.env['NPM_TOKEN']` +``` + +or via a specified environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: FOO_TOKEN +``` + +`token_env: FOO_TOKEN`internally will use `process.env['FOO_TOKEN']` + +or by directly specifying a token: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token: "token" +``` + +> Note: `token` has priority over `token_env` + +### You Must know + +* Verdaccio does not use Basic Authentication since version `v2.3.0`. All tokens generated by verdaccio are based on JWT ([JSON Web Token](https://jwt.io/)) +* Uplinks must be registries compatible with the `npm` endpoints. Eg: *verdaccio*, `sinopia@1.4.0`, *npmjs registry*, *yarn registry*, *JFrog*, *Nexus* and more. +* Setting `cache` to false will help to save space in your hard drive. This will avoid store `tarballs` but [it will keep metadata in folders](https://github.com/verdaccio/verdaccio/issues/391). +* Exceed with multiple uplinks might slow down the lookup of your packages due for each request a npm client does, verdaccio does 1 call for each uplink. +* The (timeout, maxage and fail_timeout) format follow the [NGINX measurement units](http://nginx.org/en/docs/syntax.html) \ No newline at end of file diff --git a/website/translated_docs/ko/use-cases.md b/website/translated_docs/ko/use-cases.md new file mode 100644 index 000000000..969dc9195 --- /dev/null +++ b/website/translated_docs/ko/use-cases.md @@ -0,0 +1,31 @@ +--- +id: use-cases +title: "Use Cases" +--- +## Using private packages + +You can add users and manage which users can access which packages. + +It is recommended that you define a prefix for your private packages, for example "local", so all your private things will look like this: `local-foo`. This way you can clearly separate public packages from private ones. + +## Using public packages from npmjs.org + +If some package doesn't exist in the storage, server will try to fetch it from npmjs.org. If npmjs.org is down, it serves packages from cache pretending that no other packages exist. Verdaccio will download only what's needed (= requested by clients), and this information will be cached, so if client will ask the same thing second time, it can be served without asking npmjs.org for it. + +Example: if you successfully request express@3.0.1 from this server once, you'll able to do that again (with all it's dependencies) anytime even if npmjs.org is down. But say express@3.0.0 will not be downloaded until it's actually needed by somebody. And if npmjs.org is offline, this server would say that only express@3.0.1 (= only what's in the cache) is published, but nothing else. + +## Override public packages + +If you want to use a modified version of some public package `foo`, you can just publish it to your local server, so when your type `npm install foo`, it'll consider installing your version. + +There's two options here: + +1. You want to create a separate fork and stop synchronizing with public version. + + If you want to do that, you should modify your configuration file so verdaccio won't make requests regarding this package to npmjs anymore. Add a separate entry for this package to *config.yaml* and remove `npmjs` from `proxy` list and restart the server. + + When you publish your package locally, you should probably start with version string higher than existing one, so it won't conflict with existing package in the cache. + +2. You want to temporarily use your version, but return to public one as soon as it's updated. + + In order to avoid version conflicts, you should use a custom pre-release suffix of the next patch version. For example, if a public package has version 0.1.2, you can upload 0.1.3-my-temp-fix. This way your package will be used until its original maintainer updates his public package to 0.1.3. \ No newline at end of file diff --git a/website/translated_docs/ko/web.md b/website/translated_docs/ko/web.md new file mode 100644 index 000000000..77216c021 --- /dev/null +++ b/website/translated_docs/ko/web.md @@ -0,0 +1,28 @@ +--- +id: webui +title: "Web User Interface2" +--- + + +
verdaccio@3.0.0
-`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
+`npm audit` to nowa komenda wydana razem z [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio zawiera wbudowany plugin oprogramowania pośredniego do obsługi tej komendy.
> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
diff --git a/website/translated_docs/pl/contributing.md b/website/translated_docs/pl/contributing.md
index 8631f61ba..ce4b61ed2 100644
--- a/website/translated_docs/pl/contributing.md
+++ b/website/translated_docs/pl/contributing.md
@@ -2,37 +2,37 @@
id: contributing
title: "Contributing Verdaccio"
---
-First of all Jumping into an unfamiliar code base is not easy but we are here to help you.
+First of all Zapoznanie się z obcą podstawą kodowania nie jest łatwe, ale jesteśmy tutaj, aby Ci z tym pomóc.
-## Comunication Channels
+## Kanały komunikacji
-If you are willing for asking, we use two channels for discussions:
+Jeżeli masz jakieś pytania, używamy dwóch kanałów do dyskusji:
-* [Public Discord channel](http://chat.verdaccio.org/)
+* [Publiczny kanał Discord](http://chat.verdaccio.org/)
-## Getting started
+## Pierwsze kroki
-As a first glance verdaccio is a single repository, but there are many ways you might contribute and a variety of technologies to practice.
+Na pierwszy rzut oka verdaccio jest pojedyńczym repozytorium, lecz jest wiele sposobów, dzięki którym możesz z nami współpracować i wiele technik do przećwiczenia.
### Finding my spot
-All we have different skills, so, let's see where you might feel comfortable.
+Wszyscy posiadamy różne umiejętności, więc zobaczmy w czym czujesz się komfortowo.
-### I know or I want to learn Node.js
+### Znam lub chcę się nauczyć Node.js
-Node.js is the base of `verdaccio`, we use libraries as `express`, `commander`, `request` or `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`.
+Node.js jest podstawą `verdaccio`, używamy bibliotek takich jak `express`, `commander`, `request` lub `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`.
-We have a long [list of plugins](plugins.md) ready to be used and improved but at the same time [you might create your own](dev-plugins.md).
+Posiadamy długą [listę wtyczek](plugins.md) gotową do użycia oraz rozwijania, ale również możesz [stworzyć swoją własną](dev-plugins.md).
-### I would prefer to work in the User Interface
+### Wolę pracować w interfejsie użytkownika
-Recently we have moved to modern techonologies as `React` and `element-react`. We are looking forward to see new ideas how to improve the UI.
+Od niedawna zaczęliśmy używać nowoczesnych technologii, takich jak `React` oraz `element-react`. Z niecierpliwością oczekujemy nowych pomysłów na ulepszenie interfejsu użytkownika.
### I feel more confortable improving the stack
-Of course, we will be happy to help us improving the stack, you can upgrade dependencies as `eslint`, `stylelint`, `webpack`. You migt merely improve the `webpack` configuration would be great. Any suggestion is very welcome. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
+Of course, we will be happy to help us improving the stack, you can upgrade dependencies as `eslint`, `stylelint`, `webpack`. You migt merely improve the `webpack` configuration would be great. Wszelkie propozycje są mile widziane. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
-Here some ideas:
+Tutaj jest kilka pomysłów:
* Create a common eslint rules to be used across all dependencies or plugins
* Improve Flow types definitions delivery
@@ -41,25 +41,25 @@ Here some ideas:
* We use babel and webpack across all dependencies, why not a common preset?
* Improve continous integration delivery
-### I do great Documentation
+### Robię świetne dokumentacje
-Many contributors find typos and grammar issues, that also helps to improve the overall experience for troubleshooting.
+Wiele współtwórców znajduje literówki i błędy gramatyczne, to również przyczynia się do ogólnego wrażenia podczas rozwiązywania problemów.
### I am a Designer
We have a frontend website
@@ -67,14 +67,14 @@ We have setup a project where you can choose your favourite language, if you do
[Go to Crowdin Verdaccio](https://crowdin.com/project/verdaccio)
-## I'm ready to contribute
+## Jestem gotowy do współtworzenia
-If you are thinking *"I've seen already the [repositories](repositories.md) and I'm willing to start right away"* then I have good news for you, that's the next step.
+Jeśli myślisz *"Widziałem już [repozytoria](repositories.md) i jestem gotów zacząć od razu"*, wtedy mam dla Ciebie dobrą wiadomość, która znajduje się w następnym kroku.
You will need learn how to build, [we have prepared a guide just for that](build.md).
Once you have played around with all scripts and you know how to use them, we are ready to go to the next step, run the [**Unit Test**](test.md).
-## Full list of contributors. We want to see your face here !
+## Pełna lista współtwórców. Chcemy tutaj zobaczyć Twoją twarz !
diff --git a/website/translated_docs/pl/install.md b/website/translated_docs/pl/install.md
index 45f4da937..57ded7b98 100644
--- a/website/translated_docs/pl/install.md
+++ b/website/translated_docs/pl/install.md
@@ -1,28 +1,28 @@
---
id: installation
-title: "Installation"
+title: "Instalacja"
---
-Verdaccio is a multiplatform web application. To install it, you need a few prerequisites.
+Verdaccio jest wieloplatformową aplikacją internetową. Aby ją zainstalować, musisz spełnić kilka wymagań.
-#### Prerequisites
+#### Wymagania
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.
+3. Interfejs sieci web obsługujący przeglądarki `Chrome, Firefox, Edge i IE9`.
-## Installing the CLI
+## Instalacja CLI
-`verdaccio` must be installed globaly using either of the following methods:
+`verdaccio` musi być zainstalowany globalnie używając dowolnej z poniższych metod:
-Using `npm`
+Za pomocą `npm`
```bash
npm install -g verdaccio
```
-or using `yarn`
+lub za pomocą `yarn`
```bash
yarn global add verdaccio
@@ -32,7 +32,7 @@ yarn global add verdaccio
## Basic Usage
-Once it has been installed, you only need to execute the CLI command:
+Po jego zainstalowaniu, trzeba tylko wywołać komendę CLI:
```bash
$> verdaccio
@@ -40,7 +40,7 @@ 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).
+Aby uzyskać więcej informacji o CLI, zapoznaj się z [sekcją cli](cli.md).
## Docker Image
diff --git a/website/translated_docs/pl/notifications.md b/website/translated_docs/pl/notifications.md
index 0de8cb2d1..d87e4c2b8 100644
--- a/website/translated_docs/pl/notifications.md
+++ b/website/translated_docs/pl/notifications.md
@@ -1,6 +1,6 @@
---
id: notifications
-title: "Notifications"
+title: "Powiadomienia"
---
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 `npm publish` command.
diff --git a/website/translated_docs/pl/plugins.md b/website/translated_docs/pl/plugins.md
index 86be2c914..b701fde3f 100644
--- a/website/translated_docs/pl/plugins.md
+++ b/website/translated_docs/pl/plugins.md
@@ -1,10 +1,10 @@
---
id: plugins
-title: "Plugins"
+title: "Wtyczki"
---
-Verdaccio is an plugabble aplication. It can be extended in many ways, either new authentication methods, adding endpoints or using a custom storage.
+Verdaccio jest aplikacją obsługującą wtyczki. Dzięki temu można rozszerzyć działanie aplikacji na wiele sposobów: wprowadzić nowe metody uwierzytelniania, dodawać punkty końcowe lub użyć niestandardowego magazynu danych.
-> If you are interested to develop your own plugin, read the [development](dev-plugins.md) section.
+> Jeśli jesteś zainteresowany stworzeniem swojej własnej wtyczki, przeczytaj sekcję dotyczącą [programowania](dev-plugins.md).
## Usage
@@ -21,7 +21,7 @@ $> npm install --global verdaccio-activedirectory
### Configuration
-Open the `config.yaml` file and update the `auth` section as follows:
+Otwórz plik `config.yaml` i zaktualizuj sekcję `auth` następująco:
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.
@@ -58,9 +58,9 @@ auth:
domainSuffix: 'sample.local'
```
-### Middleware Plugin Configuration
+### Konfiguracja wtyczki oprogramowania pośredniego
-This is an example how to set up a middleware plugin. All middleware plugins must be defined in the **middlewares** namespace.
+To jest przykład jak skonfigurować wtyczkę oprogramowania pośredniego. Wszystkie te wtyczki muszą mieć zdefiniowane nazwy z przestrzeni nazw **oprogramowań pośrednich**.
```yaml
middlewares:
@@ -86,7 +86,7 @@ store:
### Sinopia Plugins
-(compatible all versions)
+(kompatybilne ze wszystkimi wersjami)
* [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.
diff --git a/website/translated_docs/pl/repositories.md b/website/translated_docs/pl/repositories.md
index 604a57fd6..0c3295760 100644
--- a/website/translated_docs/pl/repositories.md
+++ b/website/translated_docs/pl/repositories.md
@@ -1,7 +1,7 @@
---
id: source-code
-title: "Source Code"
+title: "Kod źródłowy"
---
`verdaccio` is composed or multiple repositories you might contribute. Look into the **issues** tab whether there is a ticket waiting for you
-To see the complete list of repositories, [click here](https://github.com/verdaccio/verdaccio/wiki/Repositories).
\ No newline at end of file
+Aby zobaczyć pełną listę repozytoriów, [kliknij tutaj](https://github.com/verdaccio/verdaccio/wiki/Repositories).
\ No newline at end of file
diff --git a/website/translated_docs/pl/server.md b/website/translated_docs/pl/server.md
index 5cc0082ad..6ef924eab 100644
--- a/website/translated_docs/pl/server.md
+++ b/website/translated_docs/pl/server.md
@@ -1,8 +1,8 @@
---
id: server-configuration
-title: "Server Configuration"
+title: "Konfiguracja serwera"
---
-This is mostly basic linux server configuration stuff but I felt it important to document and share the steps I took to get verdaccio running permanently on my server. You will need root (or sudo) permissions for the following.
+Jest to głównie podstawowa konfiguracja serwera linux, lecz myślę, że jest to ważne, aby udokumentować i udostępnić krok po kroku jak uruchomiłem na stałe verdaccio na moim serwerze. Będziesz musiał użyć uprawnień root (lub sudo) dla następujących.
## Running as a separate user
diff --git a/website/translated_docs/pl/what-is-verdaccio.md b/website/translated_docs/pl/what-is-verdaccio.md
index dd5a07c59..7e243886e 100644
--- a/website/translated_docs/pl/what-is-verdaccio.md
+++ b/website/translated_docs/pl/what-is-verdaccio.md
@@ -1,10 +1,10 @@
---
id: what-is-verdaccio
-title: "What is Verdaccio?"
+title: "Co to jest Verdaccio?"
---
Verdaccio is a **lightweight private npm proxy registry** built in **Node.js**
-## What's a registry
+## Co to jest rejestr
* A repository for packages that implements the **CommonJS Compliant Package Registry specification** for reading package info
* Provide an API compatible with npm clients **(yarn/npm/pnpm)**
@@ -39,14 +39,14 @@ All packages that you publish are private and only accessible based in your conf
Verdaccio cache all dependencies by demand and speed up installations in local or private networks.
-## Verdaccio in a nutshell
+## Verdaccio w skrócie
-* It's a web app based on Node.js
-* It's a private npm registry
-* It's a local network proxy
+* Jest to internetowa aplikacja oparta na Node.js
+* Jest to prywatny rejestr npm
+* Jest to proxy sieci lokalnej
* It's a Pluggable application
-* It's a fairly easy install and use
-* We offer Docker and Kubernetes support
-* It is 100% compatible with yarn, npm and pnpm
+* Jest bardzo prosty w instalacji i w użyciu
+* Oferujemy wsparcie Docker i Kubernetes
+* Jest w 100% kompatybilny z yarn, npm i pnpm
* It was **forked** based on `sinopia@1.4.0` and 100% **backward compatible**.
-* Verdaccio means **A green color popular in late medieval Italy for fresco painting**.
\ No newline at end of file
+* Słowo Verdaccio oznacza **zielony kolor popularny w późnych średniowiecznych włochach w malarstwie freskowym**.
\ No newline at end of file
diff --git a/website/translated_docs/pl/windows.md b/website/translated_docs/pl/windows.md
index d0bf8aab2..0a062f8c7 100644
--- a/website/translated_docs/pl/windows.md
+++ b/website/translated_docs/pl/windows.md
@@ -1,16 +1,16 @@
---
id: windows
-title: "Installing As a Windows Service"
+title: "Instalacja jako Usługa systemu Windows"
---
-Loosely based upon the instructions found [here](http://asysadmin.tumblr.com/post/32941224574/running-nginx-on-windows-as-a-service). I crafted the following and it provided me with a fully working verdaccio service installation:
+Ogólnie, bazując na instrukcji podanej [tutaj](http://asysadmin.tumblr.com/post/32941224574/running-nginx-on-windows-as-a-service). I crafted the following and it provided me with a fully working verdaccio service installation:
-1. Create a directory for verdaccio
+1. Stwórz folder dla verdaccio
* mkdir `c:\verdaccio`
* cd `c:\verdaccio`
2. Install verdaccio locally (I ran into npm issues with global installs)
* npm install verdaccio
-3. Create your `config.yaml` file in this location `(c:\verdaccio\config.yaml)`
-4. Windows Service Setup
+3. Stwórz swój plik `config.yaml` w następującej lokalizacji `(c:\verdaccio\config.yaml)`
+4. Instalacja usługi systemu Windows
## Using NSSM
@@ -20,7 +20,7 @@ ALTERNATIVE METHOD: (WinSW package was missing when I tried to download it)
* Add the path that contains nssm.exe to the PATH
-* Open an administrative command
+* Otwórz wiersz polecenia z uprawnieniami administratora
* Run nssm install verdaccio At a minimum you must fill in the Application tab Path, Startup directory and Arguments fields. Assuming an install with node in the system path and a location of c:\verdaccio the below values will work:
@@ -46,6 +46,6 @@ ALTERNATIVE METHOD: (WinSW package was missing when I tried to download it)
Some of the above config is more verbose than I had expected, it appears as though 'workingdirectory' is ignored, but other than that, this works for me and allows my verdaccio instance to persist between restarts of the server, and also restart itself should there be any crashes of the verdaccio process.
-## Repositories
+## Repozytoria
* [verdaccio-deamon-windows](https://github.com/davidenke/verdaccio-deamon-windows)
\ No newline at end of file
diff --git a/website/translated_docs/pt-PT/ansible.md b/website/translated_docs/pt-PT/ansible.md
new file mode 100644
index 000000000..0f1b4dc38
--- /dev/null
+++ b/website/translated_docs/pt-PT/ansible.md
@@ -0,0 +1,13 @@
+---
+id: ansible
+title: "Ansible"
+---
+We have a customised solution for `verdaccio` in our organization.
+
+verdaccio@2.3.6 due #223
+
+### URL Prefix
+
+```yaml
+url_prefix: https://dev.company.local/verdaccio/
+```
+
+Since: `verdaccio@2.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 `10mb`, if you run in errors as `"request entity too large"` you may increase this value.
+
+```yaml
+max_body_size: 10mb
+```
+
+### Listen Port
+
+`verdaccio` runs by default in the port `4873`. Changing 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` it's enough to set the `listen` flag with the protocol *https://*. For more information about this section read the [ssl page](ssl.md).
+
+```yaml
+https:
+ key: ./path/verdaccio-key.pem
+ cert: ./path/verdaccio-cert.pem
+ ca: ./path/verdaccio-csr.pem
+```
+
+### Proxy
+
+Proxies are special-purpose HTTP servers designed to transfer data from remote servers to local clients.
+
+#### http_proxy and https_proxy
+
+If you have a proxy in your network you can set a `X-Forwarded-For` header using the following properties.
+
+```yaml
+http_proxy: http://something.local/
+https_proxy: https://something.local/
+```
+
+#### no_proxy
+
+This variable should contain a comma-separated list of domain extensions proxy should not be used for.
+
+```yaml
+no_proxy: localhost,127.0.0.1
+```
+
+### Notifications
+
+Enabling notifications to third-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"}'
+```
+
+> For more detailed configuration settings, please [check the source code](https://github.com/verdaccio/verdaccio/tree/master/conf).
+
+### Audit
+
+Since: verdaccio@3.0.0
+
+`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
+
+> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
+
+```yaml
+middlewares:
+ audit:
+ enabled: true
+```
\ No newline at end of file
diff --git a/website/translated_docs/pt-PT/contributing.md b/website/translated_docs/pt-PT/contributing.md
new file mode 100644
index 000000000..8631f61ba
--- /dev/null
+++ b/website/translated_docs/pt-PT/contributing.md
@@ -0,0 +1,80 @@
+---
+id: contributing
+title: "Contributing Verdaccio"
+---
+First of all Jumping into an unfamiliar code base is not easy but we are here to help you.
+
+## Comunication Channels
+
+If you are willing for asking, we use two channels for discussions:
+
+* [Public Discord channel](http://chat.verdaccio.org/)
+
+## Getting started
+
+As a first glance verdaccio is a single repository, but there are many ways you might contribute and a variety of technologies to practice.
+
+### Finding my spot
+
+All we have different skills, so, let's see where you might feel comfortable.
+
+### I know or I want to learn Node.js
+
+Node.js is the base of `verdaccio`, we use libraries as `express`, `commander`, `request` or `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`.
+
+We have a long [list of plugins](plugins.md) ready to be used and improved but at the same time [you might create your own](dev-plugins.md).
+
+### I would prefer to work in the User Interface
+
+Recently we have moved to modern techonologies as `React` and `element-react`. We are looking forward to see new ideas how to improve the UI.
+
+### I feel more confortable improving the stack
+
+Of course, we will be happy to help us improving the stack, you can upgrade dependencies as `eslint`, `stylelint`, `webpack`. You migt merely improve the `webpack` configuration would be great. Any suggestion is very welcome. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
+
+Here some ideas:
+
+* Create a common eslint rules to be used across all dependencies or plugins
+* Improve Flow types definitions delivery
+* Moving to Webpack 4
+* Improve hot reload with Webpack
+* We use babel and webpack across all dependencies, why not a common preset?
+* Improve continous integration delivery
+
+### I do great Documentation
+
+Many contributors find typos and grammar issues, that also helps to improve the overall experience for troubleshooting.
+
+### I am a Designer
+
+We have a frontend website
+
+We have setup a project where you can choose your favourite language, if you do not find your language feel free to request one [creating a ticket](https://github.com/verdaccio/verdaccio/issues/new).
+
+[Go to Crowdin Verdaccio](https://crowdin.com/project/verdaccio)
+
+## I'm ready to contribute
+
+If you are thinking *"I've seen already the [repositories](repositories.md) and I'm willing to start right away"* then I have good news for you, that's the next step.
+
+You will need learn how to build, [we have prepared a guide just for that](build.md).
+
+Once you have played around with all scripts and you know how to use them, we are ready to go to the next step, run the [**Unit Test**](test.md).
+
+## Full list of contributors. We want to see your face here !
+
+
diff --git a/website/translated_docs/pt-PT/dev-plugins.md b/website/translated_docs/pt-PT/dev-plugins.md
new file mode 100644
index 000000000..384ba171a
--- /dev/null
+++ b/website/translated_docs/pt-PT/dev-plugins.md
@@ -0,0 +1,188 @@
+---
+id: dev-plugins
+title: "Developing 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
+ 
+
+
+To pull the latest pre-built [docker image](https://hub.docker.com/r/verdaccio/verdaccio/):
+
+```bash
+docker pull verdaccio/verdaccio
+```
+
+
+
+## Tagged Versions
+
+Since version `v2.x` you can pull docker images by [tag](https://hub.docker.com/r/verdaccio/verdaccio/tags/), as follows:
+
+For a major version:
+
+```bash
+docker pull verdaccio/verdaccio:3
+```
+
+For a minor version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0
+```
+
+For a specific (patch) version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0.1
+```
+
+For the next major release using the `beta` (master branch) version.
+
+```bash
+docker pull verdaccio/verdaccio:beta
+```
+
+> If you are interested on a list of tags, [please visit the Docker Hub website](https://hub.docker.com/r/verdaccio/verdaccio/tags/).
+
+## Running verdaccio using Docker
+
+To run the docker container:
+
+```bash
+docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
+```
+
+The last argument defines which image to use. The above line will pull the latest prebuilt image from dockerhub, if you haven't done that already.
+
+If you have [build an image locally](#build-your-own-docker-image) use `verdaccio` as the last argument.
+
+You can use `-v` to bind mount `conf`, `storage` and `plugins` to the hosts filesystem:
+
+```bash
+V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio -p 4873:4873 \
+ -v $V_PATH/conf:/verdaccio/conf \
+ -v $V_PATH/storage:/verdaccio/storage \
+ -v $V_PATH/plugins:/verdaccio/plugins \
+ verdaccio/verdaccio
+```
+
+> Note: Verdaccio runs as a non-root user (uid=100, gid=101) inside the container, if you use bind mount to override default, you need to make sure the mount directory is assigned to the right user. In above example, you need to run `sudo chown -R 100:101 /opt/verdaccio` otherwise you will get permission errors at runtime. [Use docker volume](https://docs.docker.com/storage/volumes/) is recommended over using bind mount.
+
+### Plugins
+
+Plugins can be installed in a separate directory and mounted using Docker or Kubernetes, however make sure you build plugins with native dependencies using the same base image as the Verdaccio Dockerfile.
+
+### Docker and custom port configuration
+
+Any `host:port` configured in `conf/config.yaml` under `listen` is currently ignored when using docker.
+
+If you want to reach verdaccio docker instance under different port, lets say `5000` in your `docker run` command replace `-p 4873:4873` with `-p 5000:4873`.
+
+In case you need to specify which port to listen to **in the docker container**, since version 2.?.? you can do so by providing additional arguments to `docker run`: `--env PORT=5000` This changes which port the docker container exposes and the port verdaccio listens to.
+
+Of course the numbers you give to `-p` paremeter need to match, so assuming you want them to all be the same this is what you could copy, paste and adopt:
+
+```bash
+PORT=5000; docker run -it --rm --name verdaccio \
+ --env PORT -p $PORT:$PORT
+ verdaccio/verdaccio
+```
+
+### Using HTTPS with Docker
+
+You can configure the protocol verdaccio is going to listen on, similarly to the port configuration. You have to overwrite the default value("http") of the `PROTOCOL` environment variable to "https", after you specified the certificates in the config.yaml.
+
+```bash
+PROTOCOL=https; docker run -it --rm --name verdaccio \
+ --env PROTOCOL -p 4873:4873
+ verdaccio/verdaccio
+```
+
+### Using docker-compose
+
+1. Get the latest version of [docker-compose](https://github.com/docker/compose).
+2. Build and run the container:
+
+```bash
+$ docker-compose up --build
+```
+
+You can set the port to use (for both container and host) by prefixing the above command with `PORT=5000`.
+
+Docker will generate a named volume in which to store persistent application data. You can use `docker inspect` or `docker volume inspect` to reveal the physical location of the volume and edit the configuration, such as:
+
+ $ docker volume inspect verdaccio_verdaccio
+ [
+ {
+ "Name": "verdaccio_verdaccio",
+ "Driver": "local",
+ "Mountpoint": "/var/lib/docker/volumes/verdaccio_verdaccio/_data",
+ "Labels": null,
+ "Scope": "local"
+ }
+ ]
+
+
+
+## Build your own Docker image
+
+```bash
+docker build -t verdaccio .
+```
+
+There is also an npm script for building the docker image, so you can also do:
+
+```bash
+npm run build:docker
+```
+
+Note: The first build takes some minutes to build because it needs to run `npm install`, and it will take that long again whenever you change any file that is not listed in `.dockerignore`.
+
+If you want to use the docker image on a rpi or a compatible device there is also a dockerfile available. To build the docker image for raspberry pi execute:
+
+```bash
+npm run build:docker:rpi
+```
+
+Please note that for any of the above docker commands you need to have docker installed on your machine and the docker executable should be available on your `$PATH`.
+
+## Docker Examples
+
+There is a separate repository that hosts multiple configurations to compose Docker images with `verdaccio`, for instance, as reverse proxy:
+
+Alternatively, if you have a certificate as `server.pfx` format, you can add the following configuration section. The passphrase is optional and only needed, if your certificate is encrypted. + + + +https: pfx: /Users/user/.config/verdaccio/server.pfx passphrase: 'secret' ```` + +More info on the `key`, `cert`, `ca`, `pfx` and `passphrase` arguments on the [Node documentation](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) + +* Run `verdaccio` in your command line. + +* Open the browser and load `https://your.domain.com:port/` + +This instructions are mostly valid under OSX and Linux, on Windows the paths will vary but, the steps are the same. + +## Docker + +If you are using the Docker image, you have to set the `PROTOCOL` environment variable to `https` as the `listen` argument is provided on the [Dockerfile](https://github.com/verdaccio/verdaccio/blob/master/Dockerfile#L43), and thus ignored from your config file. + +You can also set the `PORT` environment variable if you are using a different port than `4873`. \ No newline at end of file diff --git a/website/translated_docs/pt-PT/test.md b/website/translated_docs/pt-PT/test.md new file mode 100644 index 000000000..818cefa16 --- /dev/null +++ b/website/translated_docs/pt-PT/test.md @@ -0,0 +1,134 @@ +--- +id: unit-testing +title: "Unit Testing" +--- +All tests are split in three folders: + +- `test/unit` - Tests that cover functions that transform data in an non-trivial way. These tests simply `require()` a few files and run code in there, so they are very fast. +- `test/functional` - Tests that launch a verdaccio instance and perform a series of requests to it over http. They are slower than unit tests. +- `test/integration` - Tests that launch a verdaccio instance and do requests to it using npm. They are really slow and can hit a real npm registry. **unmaintained test** + +Unit and functional tests are executed automatically by running `npm test` from the project's root directory. Integration tests are supposed to be executed manually from time to time. + +We use `jest` for all test. + +## The npm Script + +To run the test script you can use either `npm` or `yarn`. + + yarn run test + + +That will trigger only two first groups of test, unit and functional. + +### Using test/unit + +The following is just an example how a unit test should looks like. Basically follow the `jest` standard. + +Try to describe what exactly does the unit test in a single sentence in the header of the `test` section. + +```javacript +const verdaccio = require('../../src/api/index'); +const config = require('./partials/config'); + +describe('basic system test', () => { + + beforeAll(function(done) { + // something important + }); + + afterAll((done) => { + // undo something important + }); + + test('server should respond on /', done => { + // your test + done(); + }); +}); +``` + +### Using test/functional + +Funtional testing in verdaccio has a bit more of complextity that needs a deep explanation in order to success in your experience. + +All starts in the `index.js` file. Let's dive in into it. + +```javascript +// we create 3 server instances + const config1 = new VerdaccioConfig( + './store/test-storage', + './store/config-1.yaml', + 'http://localhost:55551/'); + const config2 = new VerdaccioConfig( + './store/test-storage2', + './store/config-2.yaml', + 'http://localhost:55552/'); + const config3 = new VerdaccioConfig( + './store/test-storage3', + './store/config-3.yaml', + 'http://localhost:55553/'); + const server1: IServerBridge = new Server(config1.domainPath); + const server2: IServerBridge = new Server(config2.domainPath); + const server3: IServerBridge = new Server(config3.domainPath); + const process1: IServerProcess = new VerdaccioProcess(config1, server1, SILENCE_LOG); + const process2: IServerProcess = new VerdaccioProcess(config2, server2, SILENCE_LOG); + const process3: IServerProcess = new VerdaccioProcess(config3, server3, SILENCE_LOG); + const express: any = new ExpressServer(); + ... + + // we check whether all instances has been started, since run in independent processes + beforeAll((done) => { + Promise.all([ + process1.init(), + process2.init(), + process3.init()]).then((forks) => { + _.map(forks, (fork) => { + processRunning.push(fork[0]); + }); + express.start(EXPRESS_PORT).then((app) =>{ + done(); + }, (err) => { + done(err); + }); + }).catch((error) => { + done(error); + }); + }); + + // after finish all, we ensure are been stoped + afterAll(() => { + _.map(processRunning, (fork) => { + fork.stop(); + }); + express.server.close(); + }); + + +``` + +### Usage + +Here we are gonna describe how it looks like an usual functional test, check inline for more detail information. + +#### The lib/server.js + +The server class is just a wrapper that simulates a `npm` client and provides a simple API for the funtional test. + +As we mention in the previous section, we are creating 3 process servers that are accessible in each process as `server1`, `server2` and ``server3`. + +Using such reference you will be able to send request to any of the 3 instance running. + +```javascript +
export default function(server) { + // we recieve any server instance via arguments + test('add tag - 404', () => { + // we interact with the server instance. + return server.addTag('testpkg-tag', 'tagtagtag', '0.0.1').status(404).body_error(/no such package/); + }); +}); +``` + +### Test/integration + +These section never has been used, but we are looking for help to make it run properly. **All new ideas are very welcome.** \ No newline at end of file diff --git a/website/translated_docs/pt-PT/uplinks.md b/website/translated_docs/pt-PT/uplinks.md new file mode 100644 index 000000000..7d0076b7d --- /dev/null +++ b/website/translated_docs/pt-PT/uplinks.md @@ -0,0 +1,86 @@ +--- +id: uplinks +title: "Uplinks" +--- +An *uplink* is a link with an external registry that provides acccess to external packages. + + + +### Usage + +```yaml +uplinks: + npmjs: + url: https://registry.npmjs.org/ + server2: + url: http://mirror.local.net/ + timeout: 100ms + server3: + url: http://mirror2.local.net:9000/ + baduplink: + url: http://localhost:55666/ +``` + +### Configuration + +You can define mutiple uplinks and each of them must have an unique name (key). They can have two properties: + +| Property | Type | Required | Example | Support | Description | Default | +| ------------ | ------- | -------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | +| url | string | Yes | https://registry.npmjs.org/ | all | The registry url | npmjs | +| ca | string | No | ~./ssl/client.crt' | all | SSL path certificate | No default | +| timeout | string | No | 100ms | all | set new timeout for the request | 30s | +| maxage | string | No | 10m | all | limit maximun failure request | 2m | +| fail_timeout | string | No | 10m | all | defines max time when a request becomes a failure | 5m | +| max_fails | number | No | 2 | all | limit maximun failure request | 2 | +| cache | boolean | No | [true,false] | >= 2.1 | cache all remote tarballs in storage | true | +| auth | list | No | [see below](uplinks.md#auth-property) | >= 2.5 | assigns the header 'Authorization' [more info](http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules) | disabled | +| headers | list | No | authorization: "Bearer SecretJWToken==" | all | list of custom headers for the uplink | disabled | +| strict_ssl | boolean | No | [true,false] | >= 3.0 | If true, requires SSL certificates be valid. | true | + +#### Auth property + +The `auth` property allows you to use an auth token with an uplink. Using the default environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: true # defaults to `process.env['NPM_TOKEN']` +``` + +or via a specified environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: FOO_TOKEN +``` + +`token_env: FOO_TOKEN`internally will use `process.env['FOO_TOKEN']` + +or by directly specifying a token: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token: "token" +``` + +> Note: `token` has priority over `token_env` + +### You Must know + +* Verdaccio does not use Basic Authentication since version `v2.3.0`. All tokens generated by verdaccio are based on JWT ([JSON Web Token](https://jwt.io/)) +* Uplinks must be registries compatible with the `npm` endpoints. Eg: *verdaccio*, `sinopia@1.4.0`, *npmjs registry*, *yarn registry*, *JFrog*, *Nexus* and more. +* Setting `cache` to false will help to save space in your hard drive. This will avoid store `tarballs` but [it will keep metadata in folders](https://github.com/verdaccio/verdaccio/issues/391). +* Exceed with multiple uplinks might slow down the lookup of your packages due for each request a npm client does, verdaccio does 1 call for each uplink. +* The (timeout, maxage and fail_timeout) format follow the [NGINX measurement units](http://nginx.org/en/docs/syntax.html) \ No newline at end of file diff --git a/website/translated_docs/pt-PT/use-cases.md b/website/translated_docs/pt-PT/use-cases.md new file mode 100644 index 000000000..969dc9195 --- /dev/null +++ b/website/translated_docs/pt-PT/use-cases.md @@ -0,0 +1,31 @@ +--- +id: use-cases +title: "Use Cases" +--- +## Using private packages + +You can add users and manage which users can access which packages. + +It is recommended that you define a prefix for your private packages, for example "local", so all your private things will look like this: `local-foo`. This way you can clearly separate public packages from private ones. + +## Using public packages from npmjs.org + +If some package doesn't exist in the storage, server will try to fetch it from npmjs.org. If npmjs.org is down, it serves packages from cache pretending that no other packages exist. Verdaccio will download only what's needed (= requested by clients), and this information will be cached, so if client will ask the same thing second time, it can be served without asking npmjs.org for it. + +Example: if you successfully request express@3.0.1 from this server once, you'll able to do that again (with all it's dependencies) anytime even if npmjs.org is down. But say express@3.0.0 will not be downloaded until it's actually needed by somebody. And if npmjs.org is offline, this server would say that only express@3.0.1 (= only what's in the cache) is published, but nothing else. + +## Override public packages + +If you want to use a modified version of some public package `foo`, you can just publish it to your local server, so when your type `npm install foo`, it'll consider installing your version. + +There's two options here: + +1. You want to create a separate fork and stop synchronizing with public version. + + If you want to do that, you should modify your configuration file so verdaccio won't make requests regarding this package to npmjs anymore. Add a separate entry for this package to *config.yaml* and remove `npmjs` from `proxy` list and restart the server. + + When you publish your package locally, you should probably start with version string higher than existing one, so it won't conflict with existing package in the cache. + +2. You want to temporarily use your version, but return to public one as soon as it's updated. + + In order to avoid version conflicts, you should use a custom pre-release suffix of the next patch version. For example, if a public package has version 0.1.2, you can upload 0.1.3-my-temp-fix. This way your package will be used until its original maintainer updates his public package to 0.1.3. \ No newline at end of file diff --git a/website/translated_docs/pt-PT/web.md b/website/translated_docs/pt-PT/web.md new file mode 100644 index 000000000..77216c021 --- /dev/null +++ b/website/translated_docs/pt-PT/web.md @@ -0,0 +1,28 @@ +--- +id: webui +title: "Web User Interface2" +--- + + +
verdaccio@2.3.6 due #223
+
+### URL Prefix
+
+```yaml
+url_prefix: https://dev.company.local/verdaccio/
+```
+
+Since: `verdaccio@2.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 `10mb`, if you run in errors as `"request entity too large"` you may increase this value.
+
+```yaml
+max_body_size: 10mb
+```
+
+### Listen Port
+
+`verdaccio` runs by default in the port `4873`. Changing 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` it's enough to set the `listen` flag with the protocol *https://*. For more information about this section read the [ssl page](ssl.md).
+
+```yaml
+https:
+ key: ./path/verdaccio-key.pem
+ cert: ./path/verdaccio-cert.pem
+ ca: ./path/verdaccio-csr.pem
+```
+
+### Proxy
+
+Proxies are special-purpose HTTP servers designed to transfer data from remote servers to local clients.
+
+#### http_proxy and https_proxy
+
+If you have a proxy in your network you can set a `X-Forwarded-For` header using the following properties.
+
+```yaml
+http_proxy: http://something.local/
+https_proxy: https://something.local/
+```
+
+#### no_proxy
+
+This variable should contain a comma-separated list of domain extensions proxy should not be used for.
+
+```yaml
+no_proxy: localhost,127.0.0.1
+```
+
+### Notifications
+
+Enabling notifications to third-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"}'
+```
+
+> For more detailed configuration settings, please [check the source code](https://github.com/verdaccio/verdaccio/tree/master/conf).
+
+### Audit
+
+Since: verdaccio@3.0.0
+
+`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
+
+> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
+
+```yaml
+middlewares:
+ audit:
+ enabled: true
+```
\ No newline at end of file
diff --git a/website/translated_docs/ru/contributing.md b/website/translated_docs/ru/contributing.md
new file mode 100644
index 000000000..8631f61ba
--- /dev/null
+++ b/website/translated_docs/ru/contributing.md
@@ -0,0 +1,80 @@
+---
+id: contributing
+title: "Contributing Verdaccio"
+---
+First of all Jumping into an unfamiliar code base is not easy but we are here to help you.
+
+## Comunication Channels
+
+If you are willing for asking, we use two channels for discussions:
+
+* [Public Discord channel](http://chat.verdaccio.org/)
+
+## Getting started
+
+As a first glance verdaccio is a single repository, but there are many ways you might contribute and a variety of technologies to practice.
+
+### Finding my spot
+
+All we have different skills, so, let's see where you might feel comfortable.
+
+### I know or I want to learn Node.js
+
+Node.js is the base of `verdaccio`, we use libraries as `express`, `commander`, `request` or `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`.
+
+We have a long [list of plugins](plugins.md) ready to be used and improved but at the same time [you might create your own](dev-plugins.md).
+
+### I would prefer to work in the User Interface
+
+Recently we have moved to modern techonologies as `React` and `element-react`. We are looking forward to see new ideas how to improve the UI.
+
+### I feel more confortable improving the stack
+
+Of course, we will be happy to help us improving the stack, you can upgrade dependencies as `eslint`, `stylelint`, `webpack`. You migt merely improve the `webpack` configuration would be great. Any suggestion is very welcome. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
+
+Here some ideas:
+
+* Create a common eslint rules to be used across all dependencies or plugins
+* Improve Flow types definitions delivery
+* Moving to Webpack 4
+* Improve hot reload with Webpack
+* We use babel and webpack across all dependencies, why not a common preset?
+* Improve continous integration delivery
+
+### I do great Documentation
+
+Many contributors find typos and grammar issues, that also helps to improve the overall experience for troubleshooting.
+
+### I am a Designer
+
+We have a frontend website
+
+We have setup a project where you can choose your favourite language, if you do not find your language feel free to request one [creating a ticket](https://github.com/verdaccio/verdaccio/issues/new).
+
+[Go to Crowdin Verdaccio](https://crowdin.com/project/verdaccio)
+
+## I'm ready to contribute
+
+If you are thinking *"I've seen already the [repositories](repositories.md) and I'm willing to start right away"* then I have good news for you, that's the next step.
+
+You will need learn how to build, [we have prepared a guide just for that](build.md).
+
+Once you have played around with all scripts and you know how to use them, we are ready to go to the next step, run the [**Unit Test**](test.md).
+
+## Full list of contributors. We want to see your face here !
+
+
diff --git a/website/translated_docs/ru/dev-plugins.md b/website/translated_docs/ru/dev-plugins.md
new file mode 100644
index 000000000..384ba171a
--- /dev/null
+++ b/website/translated_docs/ru/dev-plugins.md
@@ -0,0 +1,188 @@
+---
+id: dev-plugins
+title: "Developing 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
+ 
+
+
+To pull the latest pre-built [docker image](https://hub.docker.com/r/verdaccio/verdaccio/):
+
+```bash
+docker pull verdaccio/verdaccio
+```
+
+
+
+## Tagged Versions
+
+Since version `v2.x` you can pull docker images by [tag](https://hub.docker.com/r/verdaccio/verdaccio/tags/), as follows:
+
+For a major version:
+
+```bash
+docker pull verdaccio/verdaccio:3
+```
+
+For a minor version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0
+```
+
+For a specific (patch) version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0.1
+```
+
+For the next major release using the `beta` (master branch) version.
+
+```bash
+docker pull verdaccio/verdaccio:beta
+```
+
+> If you are interested on a list of tags, [please visit the Docker Hub website](https://hub.docker.com/r/verdaccio/verdaccio/tags/).
+
+## Running verdaccio using Docker
+
+To run the docker container:
+
+```bash
+docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
+```
+
+The last argument defines which image to use. The above line will pull the latest prebuilt image from dockerhub, if you haven't done that already.
+
+If you have [build an image locally](#build-your-own-docker-image) use `verdaccio` as the last argument.
+
+You can use `-v` to bind mount `conf`, `storage` and `plugins` to the hosts filesystem:
+
+```bash
+V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio -p 4873:4873 \
+ -v $V_PATH/conf:/verdaccio/conf \
+ -v $V_PATH/storage:/verdaccio/storage \
+ -v $V_PATH/plugins:/verdaccio/plugins \
+ verdaccio/verdaccio
+```
+
+> Note: Verdaccio runs as a non-root user (uid=100, gid=101) inside the container, if you use bind mount to override default, you need to make sure the mount directory is assigned to the right user. In above example, you need to run `sudo chown -R 100:101 /opt/verdaccio` otherwise you will get permission errors at runtime. [Use docker volume](https://docs.docker.com/storage/volumes/) is recommended over using bind mount.
+
+### Plugins
+
+Plugins can be installed in a separate directory and mounted using Docker or Kubernetes, however make sure you build plugins with native dependencies using the same base image as the Verdaccio Dockerfile.
+
+### Docker and custom port configuration
+
+Any `host:port` configured in `conf/config.yaml` under `listen` is currently ignored when using docker.
+
+If you want to reach verdaccio docker instance under different port, lets say `5000` in your `docker run` command replace `-p 4873:4873` with `-p 5000:4873`.
+
+In case you need to specify which port to listen to **in the docker container**, since version 2.?.? you can do so by providing additional arguments to `docker run`: `--env PORT=5000` This changes which port the docker container exposes and the port verdaccio listens to.
+
+Of course the numbers you give to `-p` paremeter need to match, so assuming you want them to all be the same this is what you could copy, paste and adopt:
+
+```bash
+PORT=5000; docker run -it --rm --name verdaccio \
+ --env PORT -p $PORT:$PORT
+ verdaccio/verdaccio
+```
+
+### Using HTTPS with Docker
+
+You can configure the protocol verdaccio is going to listen on, similarly to the port configuration. You have to overwrite the default value("http") of the `PROTOCOL` environment variable to "https", after you specified the certificates in the config.yaml.
+
+```bash
+PROTOCOL=https; docker run -it --rm --name verdaccio \
+ --env PROTOCOL -p 4873:4873
+ verdaccio/verdaccio
+```
+
+### Using docker-compose
+
+1. Get the latest version of [docker-compose](https://github.com/docker/compose).
+2. Build and run the container:
+
+```bash
+$ docker-compose up --build
+```
+
+You can set the port to use (for both container and host) by prefixing the above command with `PORT=5000`.
+
+Docker will generate a named volume in which to store persistent application data. You can use `docker inspect` or `docker volume inspect` to reveal the physical location of the volume and edit the configuration, such as:
+
+ $ docker volume inspect verdaccio_verdaccio
+ [
+ {
+ "Name": "verdaccio_verdaccio",
+ "Driver": "local",
+ "Mountpoint": "/var/lib/docker/volumes/verdaccio_verdaccio/_data",
+ "Labels": null,
+ "Scope": "local"
+ }
+ ]
+
+
+
+## Build your own Docker image
+
+```bash
+docker build -t verdaccio .
+```
+
+There is also an npm script for building the docker image, so you can also do:
+
+```bash
+npm run build:docker
+```
+
+Note: The first build takes some minutes to build because it needs to run `npm install`, and it will take that long again whenever you change any file that is not listed in `.dockerignore`.
+
+If you want to use the docker image on a rpi or a compatible device there is also a dockerfile available. To build the docker image for raspberry pi execute:
+
+```bash
+npm run build:docker:rpi
+```
+
+Please note that for any of the above docker commands you need to have docker installed on your machine and the docker executable should be available on your `$PATH`.
+
+## Docker Examples
+
+There is a separate repository that hosts multiple configurations to compose Docker images with `verdaccio`, for instance, as reverse proxy:
+
+Alternatively, if you have a certificate as `server.pfx` format, you can add the following configuration section. The passphrase is optional and only needed, if your certificate is encrypted. + + + +https: pfx: /Users/user/.config/verdaccio/server.pfx passphrase: 'secret' ```` + +More info on the `key`, `cert`, `ca`, `pfx` and `passphrase` arguments on the [Node documentation](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) + +* Run `verdaccio` in your command line. + +* Open the browser and load `https://your.domain.com:port/` + +This instructions are mostly valid under OSX and Linux, on Windows the paths will vary but, the steps are the same. + +## Docker + +If you are using the Docker image, you have to set the `PROTOCOL` environment variable to `https` as the `listen` argument is provided on the [Dockerfile](https://github.com/verdaccio/verdaccio/blob/master/Dockerfile#L43), and thus ignored from your config file. + +You can also set the `PORT` environment variable if you are using a different port than `4873`. \ No newline at end of file diff --git a/website/translated_docs/ru/test.md b/website/translated_docs/ru/test.md new file mode 100644 index 000000000..818cefa16 --- /dev/null +++ b/website/translated_docs/ru/test.md @@ -0,0 +1,134 @@ +--- +id: unit-testing +title: "Unit Testing" +--- +All tests are split in three folders: + +- `test/unit` - Tests that cover functions that transform data in an non-trivial way. These tests simply `require()` a few files and run code in there, so they are very fast. +- `test/functional` - Tests that launch a verdaccio instance and perform a series of requests to it over http. They are slower than unit tests. +- `test/integration` - Tests that launch a verdaccio instance and do requests to it using npm. They are really slow and can hit a real npm registry. **unmaintained test** + +Unit and functional tests are executed automatically by running `npm test` from the project's root directory. Integration tests are supposed to be executed manually from time to time. + +We use `jest` for all test. + +## The npm Script + +To run the test script you can use either `npm` or `yarn`. + + yarn run test + + +That will trigger only two first groups of test, unit and functional. + +### Using test/unit + +The following is just an example how a unit test should looks like. Basically follow the `jest` standard. + +Try to describe what exactly does the unit test in a single sentence in the header of the `test` section. + +```javacript +const verdaccio = require('../../src/api/index'); +const config = require('./partials/config'); + +describe('basic system test', () => { + + beforeAll(function(done) { + // something important + }); + + afterAll((done) => { + // undo something important + }); + + test('server should respond on /', done => { + // your test + done(); + }); +}); +``` + +### Using test/functional + +Funtional testing in verdaccio has a bit more of complextity that needs a deep explanation in order to success in your experience. + +All starts in the `index.js` file. Let's dive in into it. + +```javascript +// we create 3 server instances + const config1 = new VerdaccioConfig( + './store/test-storage', + './store/config-1.yaml', + 'http://localhost:55551/'); + const config2 = new VerdaccioConfig( + './store/test-storage2', + './store/config-2.yaml', + 'http://localhost:55552/'); + const config3 = new VerdaccioConfig( + './store/test-storage3', + './store/config-3.yaml', + 'http://localhost:55553/'); + const server1: IServerBridge = new Server(config1.domainPath); + const server2: IServerBridge = new Server(config2.domainPath); + const server3: IServerBridge = new Server(config3.domainPath); + const process1: IServerProcess = new VerdaccioProcess(config1, server1, SILENCE_LOG); + const process2: IServerProcess = new VerdaccioProcess(config2, server2, SILENCE_LOG); + const process3: IServerProcess = new VerdaccioProcess(config3, server3, SILENCE_LOG); + const express: any = new ExpressServer(); + ... + + // we check whether all instances has been started, since run in independent processes + beforeAll((done) => { + Promise.all([ + process1.init(), + process2.init(), + process3.init()]).then((forks) => { + _.map(forks, (fork) => { + processRunning.push(fork[0]); + }); + express.start(EXPRESS_PORT).then((app) =>{ + done(); + }, (err) => { + done(err); + }); + }).catch((error) => { + done(error); + }); + }); + + // after finish all, we ensure are been stoped + afterAll(() => { + _.map(processRunning, (fork) => { + fork.stop(); + }); + express.server.close(); + }); + + +``` + +### Usage + +Here we are gonna describe how it looks like an usual functional test, check inline for more detail information. + +#### The lib/server.js + +The server class is just a wrapper that simulates a `npm` client and provides a simple API for the funtional test. + +As we mention in the previous section, we are creating 3 process servers that are accessible in each process as `server1`, `server2` and ``server3`. + +Using such reference you will be able to send request to any of the 3 instance running. + +```javascript +
export default function(server) { + // we recieve any server instance via arguments + test('add tag - 404', () => { + // we interact with the server instance. + return server.addTag('testpkg-tag', 'tagtagtag', '0.0.1').status(404).body_error(/no such package/); + }); +}); +``` + +### Test/integration + +These section never has been used, but we are looking for help to make it run properly. **All new ideas are very welcome.** \ No newline at end of file diff --git a/website/translated_docs/ru/uplinks.md b/website/translated_docs/ru/uplinks.md new file mode 100644 index 000000000..7d0076b7d --- /dev/null +++ b/website/translated_docs/ru/uplinks.md @@ -0,0 +1,86 @@ +--- +id: uplinks +title: "Uplinks" +--- +An *uplink* is a link with an external registry that provides acccess to external packages. + + + +### Usage + +```yaml +uplinks: + npmjs: + url: https://registry.npmjs.org/ + server2: + url: http://mirror.local.net/ + timeout: 100ms + server3: + url: http://mirror2.local.net:9000/ + baduplink: + url: http://localhost:55666/ +``` + +### Configuration + +You can define mutiple uplinks and each of them must have an unique name (key). They can have two properties: + +| Property | Type | Required | Example | Support | Description | Default | +| ------------ | ------- | -------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | +| url | string | Yes | https://registry.npmjs.org/ | all | The registry url | npmjs | +| ca | string | No | ~./ssl/client.crt' | all | SSL path certificate | No default | +| timeout | string | No | 100ms | all | set new timeout for the request | 30s | +| maxage | string | No | 10m | all | limit maximun failure request | 2m | +| fail_timeout | string | No | 10m | all | defines max time when a request becomes a failure | 5m | +| max_fails | number | No | 2 | all | limit maximun failure request | 2 | +| cache | boolean | No | [true,false] | >= 2.1 | cache all remote tarballs in storage | true | +| auth | list | No | [see below](uplinks.md#auth-property) | >= 2.5 | assigns the header 'Authorization' [more info](http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules) | disabled | +| headers | list | No | authorization: "Bearer SecretJWToken==" | all | list of custom headers for the uplink | disabled | +| strict_ssl | boolean | No | [true,false] | >= 3.0 | If true, requires SSL certificates be valid. | true | + +#### Auth property + +The `auth` property allows you to use an auth token with an uplink. Using the default environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: true # defaults to `process.env['NPM_TOKEN']` +``` + +or via a specified environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: FOO_TOKEN +``` + +`token_env: FOO_TOKEN`internally will use `process.env['FOO_TOKEN']` + +or by directly specifying a token: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token: "token" +``` + +> Note: `token` has priority over `token_env` + +### You Must know + +* Verdaccio does not use Basic Authentication since version `v2.3.0`. All tokens generated by verdaccio are based on JWT ([JSON Web Token](https://jwt.io/)) +* Uplinks must be registries compatible with the `npm` endpoints. Eg: *verdaccio*, `sinopia@1.4.0`, *npmjs registry*, *yarn registry*, *JFrog*, *Nexus* and more. +* Setting `cache` to false will help to save space in your hard drive. This will avoid store `tarballs` but [it will keep metadata in folders](https://github.com/verdaccio/verdaccio/issues/391). +* Exceed with multiple uplinks might slow down the lookup of your packages due for each request a npm client does, verdaccio does 1 call for each uplink. +* The (timeout, maxage and fail_timeout) format follow the [NGINX measurement units](http://nginx.org/en/docs/syntax.html) \ No newline at end of file diff --git a/website/translated_docs/ru/use-cases.md b/website/translated_docs/ru/use-cases.md new file mode 100644 index 000000000..969dc9195 --- /dev/null +++ b/website/translated_docs/ru/use-cases.md @@ -0,0 +1,31 @@ +--- +id: use-cases +title: "Use Cases" +--- +## Using private packages + +You can add users and manage which users can access which packages. + +It is recommended that you define a prefix for your private packages, for example "local", so all your private things will look like this: `local-foo`. This way you can clearly separate public packages from private ones. + +## Using public packages from npmjs.org + +If some package doesn't exist in the storage, server will try to fetch it from npmjs.org. If npmjs.org is down, it serves packages from cache pretending that no other packages exist. Verdaccio will download only what's needed (= requested by clients), and this information will be cached, so if client will ask the same thing second time, it can be served without asking npmjs.org for it. + +Example: if you successfully request express@3.0.1 from this server once, you'll able to do that again (with all it's dependencies) anytime even if npmjs.org is down. But say express@3.0.0 will not be downloaded until it's actually needed by somebody. And if npmjs.org is offline, this server would say that only express@3.0.1 (= only what's in the cache) is published, but nothing else. + +## Override public packages + +If you want to use a modified version of some public package `foo`, you can just publish it to your local server, so when your type `npm install foo`, it'll consider installing your version. + +There's two options here: + +1. You want to create a separate fork and stop synchronizing with public version. + + If you want to do that, you should modify your configuration file so verdaccio won't make requests regarding this package to npmjs anymore. Add a separate entry for this package to *config.yaml* and remove `npmjs` from `proxy` list and restart the server. + + When you publish your package locally, you should probably start with version string higher than existing one, so it won't conflict with existing package in the cache. + +2. You want to temporarily use your version, but return to public one as soon as it's updated. + + In order to avoid version conflicts, you should use a custom pre-release suffix of the next patch version. For example, if a public package has version 0.1.2, you can upload 0.1.3-my-temp-fix. This way your package will be used until its original maintainer updates his public package to 0.1.3. \ No newline at end of file diff --git a/website/translated_docs/ru/web.md b/website/translated_docs/ru/web.md new file mode 100644 index 000000000..77216c021 --- /dev/null +++ b/website/translated_docs/ru/web.md @@ -0,0 +1,28 @@ +--- +id: webui +title: "Web User Interface2" +--- + + +
verdaccio@2.3.6 due #223
+
+### URL Prefix
+
+```yaml
+url_prefix: https://dev.company.local/verdaccio/
+```
+
+Since: `verdaccio@2.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 `10mb`, if you run in errors as `"request entity too large"` you may increase this value.
+
+```yaml
+max_body_size: 10mb
+```
+
+### Listen Port
+
+`verdaccio` runs by default in the port `4873`. Changing 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` it's enough to set the `listen` flag with the protocol *https://*. For more information about this section read the [ssl page](ssl.md).
+
+```yaml
+https:
+ key: ./path/verdaccio-key.pem
+ cert: ./path/verdaccio-cert.pem
+ ca: ./path/verdaccio-csr.pem
+```
+
+### Proxy
+
+Proxies are special-purpose HTTP servers designed to transfer data from remote servers to local clients.
+
+#### http_proxy and https_proxy
+
+If you have a proxy in your network you can set a `X-Forwarded-For` header using the following properties.
+
+```yaml
+http_proxy: http://something.local/
+https_proxy: https://something.local/
+```
+
+#### no_proxy
+
+This variable should contain a comma-separated list of domain extensions proxy should not be used for.
+
+```yaml
+no_proxy: localhost,127.0.0.1
+```
+
+### Notifications
+
+Enabling notifications to third-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"}'
+```
+
+> For more detailed configuration settings, please [check the source code](https://github.com/verdaccio/verdaccio/tree/master/conf).
+
+### Audit
+
+Since: verdaccio@3.0.0
+
+`npm audit` is a new command released with [npm 6.x](https://github.com/npm/npm/releases/tag/v6.1.0). Verdaccio includes a built-in middleware plugin to handle this command.
+
+> If you have a new installation it comes by default, otherwise you need to add the following props to your config file
+
+```yaml
+middlewares:
+ audit:
+ enabled: true
+```
\ No newline at end of file
diff --git a/website/translated_docs/vi/contributing.md b/website/translated_docs/vi/contributing.md
new file mode 100644
index 000000000..8631f61ba
--- /dev/null
+++ b/website/translated_docs/vi/contributing.md
@@ -0,0 +1,80 @@
+---
+id: contributing
+title: "Contributing Verdaccio"
+---
+First of all Jumping into an unfamiliar code base is not easy but we are here to help you.
+
+## Comunication Channels
+
+If you are willing for asking, we use two channels for discussions:
+
+* [Public Discord channel](http://chat.verdaccio.org/)
+
+## Getting started
+
+As a first glance verdaccio is a single repository, but there are many ways you might contribute and a variety of technologies to practice.
+
+### Finding my spot
+
+All we have different skills, so, let's see where you might feel comfortable.
+
+### I know or I want to learn Node.js
+
+Node.js is the base of `verdaccio`, we use libraries as `express`, `commander`, `request` or `async`. Verdaccio is basically a Rest API that create a communication with `npm` clients compatible, as `yarn`.
+
+We have a long [list of plugins](plugins.md) ready to be used and improved but at the same time [you might create your own](dev-plugins.md).
+
+### I would prefer to work in the User Interface
+
+Recently we have moved to modern techonologies as `React` and `element-react`. We are looking forward to see new ideas how to improve the UI.
+
+### I feel more confortable improving the stack
+
+Of course, we will be happy to help us improving the stack, you can upgrade dependencies as `eslint`, `stylelint`, `webpack`. You migt merely improve the `webpack` configuration would be great. Any suggestion is very welcome. Furthermore whether you have experience with **Yeoman** you might help us with the [verdaccio generator](https://github.com/verdaccio/generator-verdaccio-plugin).
+
+Here some ideas:
+
+* Create a common eslint rules to be used across all dependencies or plugins
+* Improve Flow types definitions delivery
+* Moving to Webpack 4
+* Improve hot reload with Webpack
+* We use babel and webpack across all dependencies, why not a common preset?
+* Improve continous integration delivery
+
+### I do great Documentation
+
+Many contributors find typos and grammar issues, that also helps to improve the overall experience for troubleshooting.
+
+### I am a Designer
+
+We have a frontend website
+
+We have setup a project where you can choose your favourite language, if you do not find your language feel free to request one [creating a ticket](https://github.com/verdaccio/verdaccio/issues/new).
+
+[Go to Crowdin Verdaccio](https://crowdin.com/project/verdaccio)
+
+## I'm ready to contribute
+
+If you are thinking *"I've seen already the [repositories](repositories.md) and I'm willing to start right away"* then I have good news for you, that's the next step.
+
+You will need learn how to build, [we have prepared a guide just for that](build.md).
+
+Once you have played around with all scripts and you know how to use them, we are ready to go to the next step, run the [**Unit Test**](test.md).
+
+## Full list of contributors. We want to see your face here !
+
+
diff --git a/website/translated_docs/vi/dev-plugins.md b/website/translated_docs/vi/dev-plugins.md
new file mode 100644
index 000000000..384ba171a
--- /dev/null
+++ b/website/translated_docs/vi/dev-plugins.md
@@ -0,0 +1,188 @@
+---
+id: dev-plugins
+title: "Developing 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
+ 
+
+
+To pull the latest pre-built [docker image](https://hub.docker.com/r/verdaccio/verdaccio/):
+
+```bash
+docker pull verdaccio/verdaccio
+```
+
+
+
+## Tagged Versions
+
+Since version `v2.x` you can pull docker images by [tag](https://hub.docker.com/r/verdaccio/verdaccio/tags/), as follows:
+
+For a major version:
+
+```bash
+docker pull verdaccio/verdaccio:3
+```
+
+For a minor version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0
+```
+
+For a specific (patch) version:
+
+```bash
+docker pull verdaccio/verdaccio:3.0.1
+```
+
+For the next major release using the `beta` (master branch) version.
+
+```bash
+docker pull verdaccio/verdaccio:beta
+```
+
+> If you are interested on a list of tags, [please visit the Docker Hub website](https://hub.docker.com/r/verdaccio/verdaccio/tags/).
+
+## Running verdaccio using Docker
+
+To run the docker container:
+
+```bash
+docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
+```
+
+The last argument defines which image to use. The above line will pull the latest prebuilt image from dockerhub, if you haven't done that already.
+
+If you have [build an image locally](#build-your-own-docker-image) use `verdaccio` as the last argument.
+
+You can use `-v` to bind mount `conf`, `storage` and `plugins` to the hosts filesystem:
+
+```bash
+V_PATH=/path/for/verdaccio; docker run -it --rm --name verdaccio -p 4873:4873 \
+ -v $V_PATH/conf:/verdaccio/conf \
+ -v $V_PATH/storage:/verdaccio/storage \
+ -v $V_PATH/plugins:/verdaccio/plugins \
+ verdaccio/verdaccio
+```
+
+> Note: Verdaccio runs as a non-root user (uid=100, gid=101) inside the container, if you use bind mount to override default, you need to make sure the mount directory is assigned to the right user. In above example, you need to run `sudo chown -R 100:101 /opt/verdaccio` otherwise you will get permission errors at runtime. [Use docker volume](https://docs.docker.com/storage/volumes/) is recommended over using bind mount.
+
+### Plugins
+
+Plugins can be installed in a separate directory and mounted using Docker or Kubernetes, however make sure you build plugins with native dependencies using the same base image as the Verdaccio Dockerfile.
+
+### Docker and custom port configuration
+
+Any `host:port` configured in `conf/config.yaml` under `listen` is currently ignored when using docker.
+
+If you want to reach verdaccio docker instance under different port, lets say `5000` in your `docker run` command replace `-p 4873:4873` with `-p 5000:4873`.
+
+In case you need to specify which port to listen to **in the docker container**, since version 2.?.? you can do so by providing additional arguments to `docker run`: `--env PORT=5000` This changes which port the docker container exposes and the port verdaccio listens to.
+
+Of course the numbers you give to `-p` paremeter need to match, so assuming you want them to all be the same this is what you could copy, paste and adopt:
+
+```bash
+PORT=5000; docker run -it --rm --name verdaccio \
+ --env PORT -p $PORT:$PORT
+ verdaccio/verdaccio
+```
+
+### Using HTTPS with Docker
+
+You can configure the protocol verdaccio is going to listen on, similarly to the port configuration. You have to overwrite the default value("http") of the `PROTOCOL` environment variable to "https", after you specified the certificates in the config.yaml.
+
+```bash
+PROTOCOL=https; docker run -it --rm --name verdaccio \
+ --env PROTOCOL -p 4873:4873
+ verdaccio/verdaccio
+```
+
+### Using docker-compose
+
+1. Get the latest version of [docker-compose](https://github.com/docker/compose).
+2. Build and run the container:
+
+```bash
+$ docker-compose up --build
+```
+
+You can set the port to use (for both container and host) by prefixing the above command with `PORT=5000`.
+
+Docker will generate a named volume in which to store persistent application data. You can use `docker inspect` or `docker volume inspect` to reveal the physical location of the volume and edit the configuration, such as:
+
+ $ docker volume inspect verdaccio_verdaccio
+ [
+ {
+ "Name": "verdaccio_verdaccio",
+ "Driver": "local",
+ "Mountpoint": "/var/lib/docker/volumes/verdaccio_verdaccio/_data",
+ "Labels": null,
+ "Scope": "local"
+ }
+ ]
+
+
+
+## Build your own Docker image
+
+```bash
+docker build -t verdaccio .
+```
+
+There is also an npm script for building the docker image, so you can also do:
+
+```bash
+npm run build:docker
+```
+
+Note: The first build takes some minutes to build because it needs to run `npm install`, and it will take that long again whenever you change any file that is not listed in `.dockerignore`.
+
+If you want to use the docker image on a rpi or a compatible device there is also a dockerfile available. To build the docker image for raspberry pi execute:
+
+```bash
+npm run build:docker:rpi
+```
+
+Please note that for any of the above docker commands you need to have docker installed on your machine and the docker executable should be available on your `$PATH`.
+
+## Docker Examples
+
+There is a separate repository that hosts multiple configurations to compose Docker images with `verdaccio`, for instance, as reverse proxy:
+
+Alternatively, if you have a certificate as `server.pfx` format, you can add the following configuration section. The passphrase is optional and only needed, if your certificate is encrypted. + + + +https: pfx: /Users/user/.config/verdaccio/server.pfx passphrase: 'secret' ```` + +More info on the `key`, `cert`, `ca`, `pfx` and `passphrase` arguments on the [Node documentation](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) + +* Run `verdaccio` in your command line. + +* Open the browser and load `https://your.domain.com:port/` + +This instructions are mostly valid under OSX and Linux, on Windows the paths will vary but, the steps are the same. + +## Docker + +If you are using the Docker image, you have to set the `PROTOCOL` environment variable to `https` as the `listen` argument is provided on the [Dockerfile](https://github.com/verdaccio/verdaccio/blob/master/Dockerfile#L43), and thus ignored from your config file. + +You can also set the `PORT` environment variable if you are using a different port than `4873`. \ No newline at end of file diff --git a/website/translated_docs/vi/test.md b/website/translated_docs/vi/test.md new file mode 100644 index 000000000..818cefa16 --- /dev/null +++ b/website/translated_docs/vi/test.md @@ -0,0 +1,134 @@ +--- +id: unit-testing +title: "Unit Testing" +--- +All tests are split in three folders: + +- `test/unit` - Tests that cover functions that transform data in an non-trivial way. These tests simply `require()` a few files and run code in there, so they are very fast. +- `test/functional` - Tests that launch a verdaccio instance and perform a series of requests to it over http. They are slower than unit tests. +- `test/integration` - Tests that launch a verdaccio instance and do requests to it using npm. They are really slow and can hit a real npm registry. **unmaintained test** + +Unit and functional tests are executed automatically by running `npm test` from the project's root directory. Integration tests are supposed to be executed manually from time to time. + +We use `jest` for all test. + +## The npm Script + +To run the test script you can use either `npm` or `yarn`. + + yarn run test + + +That will trigger only two first groups of test, unit and functional. + +### Using test/unit + +The following is just an example how a unit test should looks like. Basically follow the `jest` standard. + +Try to describe what exactly does the unit test in a single sentence in the header of the `test` section. + +```javacript +const verdaccio = require('../../src/api/index'); +const config = require('./partials/config'); + +describe('basic system test', () => { + + beforeAll(function(done) { + // something important + }); + + afterAll((done) => { + // undo something important + }); + + test('server should respond on /', done => { + // your test + done(); + }); +}); +``` + +### Using test/functional + +Funtional testing in verdaccio has a bit more of complextity that needs a deep explanation in order to success in your experience. + +All starts in the `index.js` file. Let's dive in into it. + +```javascript +// we create 3 server instances + const config1 = new VerdaccioConfig( + './store/test-storage', + './store/config-1.yaml', + 'http://localhost:55551/'); + const config2 = new VerdaccioConfig( + './store/test-storage2', + './store/config-2.yaml', + 'http://localhost:55552/'); + const config3 = new VerdaccioConfig( + './store/test-storage3', + './store/config-3.yaml', + 'http://localhost:55553/'); + const server1: IServerBridge = new Server(config1.domainPath); + const server2: IServerBridge = new Server(config2.domainPath); + const server3: IServerBridge = new Server(config3.domainPath); + const process1: IServerProcess = new VerdaccioProcess(config1, server1, SILENCE_LOG); + const process2: IServerProcess = new VerdaccioProcess(config2, server2, SILENCE_LOG); + const process3: IServerProcess = new VerdaccioProcess(config3, server3, SILENCE_LOG); + const express: any = new ExpressServer(); + ... + + // we check whether all instances has been started, since run in independent processes + beforeAll((done) => { + Promise.all([ + process1.init(), + process2.init(), + process3.init()]).then((forks) => { + _.map(forks, (fork) => { + processRunning.push(fork[0]); + }); + express.start(EXPRESS_PORT).then((app) =>{ + done(); + }, (err) => { + done(err); + }); + }).catch((error) => { + done(error); + }); + }); + + // after finish all, we ensure are been stoped + afterAll(() => { + _.map(processRunning, (fork) => { + fork.stop(); + }); + express.server.close(); + }); + + +``` + +### Usage + +Here we are gonna describe how it looks like an usual functional test, check inline for more detail information. + +#### The lib/server.js + +The server class is just a wrapper that simulates a `npm` client and provides a simple API for the funtional test. + +As we mention in the previous section, we are creating 3 process servers that are accessible in each process as `server1`, `server2` and ``server3`. + +Using such reference you will be able to send request to any of the 3 instance running. + +```javascript +
export default function(server) { + // we recieve any server instance via arguments + test('add tag - 404', () => { + // we interact with the server instance. + return server.addTag('testpkg-tag', 'tagtagtag', '0.0.1').status(404).body_error(/no such package/); + }); +}); +``` + +### Test/integration + +These section never has been used, but we are looking for help to make it run properly. **All new ideas are very welcome.** \ No newline at end of file diff --git a/website/translated_docs/vi/uplinks.md b/website/translated_docs/vi/uplinks.md new file mode 100644 index 000000000..7d0076b7d --- /dev/null +++ b/website/translated_docs/vi/uplinks.md @@ -0,0 +1,86 @@ +--- +id: uplinks +title: "Uplinks" +--- +An *uplink* is a link with an external registry that provides acccess to external packages. + + + +### Usage + +```yaml +uplinks: + npmjs: + url: https://registry.npmjs.org/ + server2: + url: http://mirror.local.net/ + timeout: 100ms + server3: + url: http://mirror2.local.net:9000/ + baduplink: + url: http://localhost:55666/ +``` + +### Configuration + +You can define mutiple uplinks and each of them must have an unique name (key). They can have two properties: + +| Property | Type | Required | Example | Support | Description | Default | +| ------------ | ------- | -------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- | +| url | string | Yes | https://registry.npmjs.org/ | all | The registry url | npmjs | +| ca | string | No | ~./ssl/client.crt' | all | SSL path certificate | No default | +| timeout | string | No | 100ms | all | set new timeout for the request | 30s | +| maxage | string | No | 10m | all | limit maximun failure request | 2m | +| fail_timeout | string | No | 10m | all | defines max time when a request becomes a failure | 5m | +| max_fails | number | No | 2 | all | limit maximun failure request | 2 | +| cache | boolean | No | [true,false] | >= 2.1 | cache all remote tarballs in storage | true | +| auth | list | No | [see below](uplinks.md#auth-property) | >= 2.5 | assigns the header 'Authorization' [more info](http://blog.npmjs.org/post/118393368555/deploying-with-npm-private-modules) | disabled | +| headers | list | No | authorization: "Bearer SecretJWToken==" | all | list of custom headers for the uplink | disabled | +| strict_ssl | boolean | No | [true,false] | >= 3.0 | If true, requires SSL certificates be valid. | true | + +#### Auth property + +The `auth` property allows you to use an auth token with an uplink. Using the default environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: true # defaults to `process.env['NPM_TOKEN']` +``` + +or via a specified environment variable: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token_env: FOO_TOKEN +``` + +`token_env: FOO_TOKEN`internally will use `process.env['FOO_TOKEN']` + +or by directly specifying a token: + +```yaml +uplinks: + private: + url: https://private-registry.domain.com/registry + auth: + type: bearer + token: "token" +``` + +> Note: `token` has priority over `token_env` + +### You Must know + +* Verdaccio does not use Basic Authentication since version `v2.3.0`. All tokens generated by verdaccio are based on JWT ([JSON Web Token](https://jwt.io/)) +* Uplinks must be registries compatible with the `npm` endpoints. Eg: *verdaccio*, `sinopia@1.4.0`, *npmjs registry*, *yarn registry*, *JFrog*, *Nexus* and more. +* Setting `cache` to false will help to save space in your hard drive. This will avoid store `tarballs` but [it will keep metadata in folders](https://github.com/verdaccio/verdaccio/issues/391). +* Exceed with multiple uplinks might slow down the lookup of your packages due for each request a npm client does, verdaccio does 1 call for each uplink. +* The (timeout, maxage and fail_timeout) format follow the [NGINX measurement units](http://nginx.org/en/docs/syntax.html) \ No newline at end of file diff --git a/website/translated_docs/vi/use-cases.md b/website/translated_docs/vi/use-cases.md new file mode 100644 index 000000000..969dc9195 --- /dev/null +++ b/website/translated_docs/vi/use-cases.md @@ -0,0 +1,31 @@ +--- +id: use-cases +title: "Use Cases" +--- +## Using private packages + +You can add users and manage which users can access which packages. + +It is recommended that you define a prefix for your private packages, for example "local", so all your private things will look like this: `local-foo`. This way you can clearly separate public packages from private ones. + +## Using public packages from npmjs.org + +If some package doesn't exist in the storage, server will try to fetch it from npmjs.org. If npmjs.org is down, it serves packages from cache pretending that no other packages exist. Verdaccio will download only what's needed (= requested by clients), and this information will be cached, so if client will ask the same thing second time, it can be served without asking npmjs.org for it. + +Example: if you successfully request express@3.0.1 from this server once, you'll able to do that again (with all it's dependencies) anytime even if npmjs.org is down. But say express@3.0.0 will not be downloaded until it's actually needed by somebody. And if npmjs.org is offline, this server would say that only express@3.0.1 (= only what's in the cache) is published, but nothing else. + +## Override public packages + +If you want to use a modified version of some public package `foo`, you can just publish it to your local server, so when your type `npm install foo`, it'll consider installing your version. + +There's two options here: + +1. You want to create a separate fork and stop synchronizing with public version. + + If you want to do that, you should modify your configuration file so verdaccio won't make requests regarding this package to npmjs anymore. Add a separate entry for this package to *config.yaml* and remove `npmjs` from `proxy` list and restart the server. + + When you publish your package locally, you should probably start with version string higher than existing one, so it won't conflict with existing package in the cache. + +2. You want to temporarily use your version, but return to public one as soon as it's updated. + + In order to avoid version conflicts, you should use a custom pre-release suffix of the next patch version. For example, if a public package has version 0.1.2, you can upload 0.1.3-my-temp-fix. This way your package will be used until its original maintainer updates his public package to 0.1.3. \ No newline at end of file diff --git a/website/translated_docs/vi/web.md b/website/translated_docs/vi/web.md new file mode 100644 index 000000000..77216c021 --- /dev/null +++ b/website/translated_docs/vi/web.md @@ -0,0 +1,28 @@ +--- +id: webui +title: "Web User Interface2" +--- + + +