mirror of
https://github.com/verdaccio/verdaccio.git
synced 2025-02-21 07:29:37 +01:00
website docs refactor the "Using a private registry" section (#3247)
This commit is contained in:
Felipe Plets
GitHub
parent
353aa62fff
commit
7a99b11be3
@ -3,155 +3,8 @@ id: cli-registry
|
||||
title: "Using a private registry"
|
||||
---
|
||||
|
||||
Setting up a private registry can be achieved in a few ways, let's review all of them. The following commands might be different based on the package manager you are using.
|
||||
Setting up a private registry is quite easy on all major Package managers and can be achieved in a few different ways depenging on your goals. The following links details how you can achieve this goal for each major package manager.
|
||||
|
||||
### npm (5.x, 6.x) {#npm-5x-6x}
|
||||
|
||||
To set the registry in the `.npmrc` file use the following:
|
||||
|
||||
```bash
|
||||
npm set registry http://localhost:4873/
|
||||
```
|
||||
|
||||
If you want one single use `--registry` after the required command.
|
||||
|
||||
```bash
|
||||
npm install --registry http://localhost:4873
|
||||
```
|
||||
|
||||
Write it yourself by defining in your `.npmrc` a `registry` field.
|
||||
|
||||
```bash title=".npmrc"
|
||||
registry=http://localhost:4873
|
||||
```
|
||||
|
||||
> Since `npm@5.x` [ignores the `resolve` field in defined in the lock files](https://medium.com/verdaccio/verdaccio-and-deterministic-lock-files-5339d82d611e), while `pnpm@4.x` and `yarn@1.x` does the opposite.
|
||||
|
||||
Or a `publishConfig` in your `package.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"publishConfig": {
|
||||
"registry": "http://localhost:4873"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> By using the `publishConfig` the previous two options would be ignored, only use this option if you want to ensure the package is not being published anywhere else.
|
||||
|
||||
If you are using either `npm@5.4.x` or `npm@5.5.x`, there are [known issues with tokens](https://github.com/verdaccio/verdaccio/issues/509#issuecomment-359193762), please upgrade to either `6.x` or downgrade to `npm@5.3.0`.
|
||||
|
||||
#### SSL and certificates {#ssl-and-certificates}
|
||||
|
||||
When using Verdaccio under SSL without a valid certificate, defining `strict-ssl` in your config file is required otherwise you will get `SSL Error: SELF_SIGNED_CERT_IN_CHAIN` errors.
|
||||
|
||||
`npm` does not support [invalid certificates anymore](https://blog.npmjs.org/post/78085451721/npms-self-signed-certificate-is-no-more) since 2014.
|
||||
|
||||
```bash
|
||||
npm config set ca ""
|
||||
npm config set strict-ssl false
|
||||
```
|
||||
|
||||
### npm (7.x) {#npm-7x}
|
||||
|
||||
npm `v7.0.0` is more strict with the new `v2` lockfile. If you have mixed `resolved` fields in your lockfile, for instance, having this in your lockfile:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "npm7",
|
||||
"version": "1.0.0",
|
||||
"lockfileVersion": 2,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"version": "1.0.0",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"lodash": "4.17.20",
|
||||
"underscore": "^1.11.0"
|
||||
}
|
||||
},
|
||||
..... // removed for simplicity
|
||||
},
|
||||
"dependencies": {
|
||||
"lodash": {
|
||||
"version": "4.17.20",
|
||||
"resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz",
|
||||
"integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA=="
|
||||
},
|
||||
"underscore": {
|
||||
"version": "1.11.0",
|
||||
"resolved": "http://localhost:4873/underscore/-/underscore-1.11.0.tgz",
|
||||
"integrity": "sha512-xY96SsN3NA461qIRKZ/+qox37YXPtSBswMGfiNptr+wrt6ds4HaMw23TP612fEyGekRE6LNRiLYr/aqbHXNedw=="
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Either running `npm i --registry https://registry.npmjs.org` or using `.npmrc` will fail your installation.
|
||||
|
||||
### yarn {#yarn}
|
||||
|
||||
#### Yarn (1.x) {#yarn-1x}
|
||||
|
||||
> Be aware npm configurations are valid on the classic version
|
||||
|
||||
The classic version is able to regonize the `.npmrc` file, but also provides their own configuration file named `.yarnrc`.
|
||||
|
||||
To set up a registry, create a file and define a registry.
|
||||
|
||||
```
|
||||
// .yarnrc
|
||||
registry "http://localhost:4873"
|
||||
```
|
||||
|
||||
By using this version you should enable `always-auth` in your configuration running:
|
||||
|
||||
```
|
||||
npm config set always-auth true
|
||||
```
|
||||
|
||||
`yarn@1.x` does not send the authorization header on `yarn install` if your packages requires authentication, by enabling `always-auth` will force yarn do it on each request.
|
||||
|
||||
#### Yarn Berry (>=2.x) {#yarn-berry-2x}
|
||||
|
||||
> Yarn berry does not recognize `--registry` or `.npmrc` file anymore.
|
||||
|
||||
For defining a registry you must use the `.yarnrc.yml` located in the root of your project or global configuration.
|
||||
|
||||
When you publish a package the `npmRegistryServer` must be used. Keep in mind the `publishConfig.registry` in the `package.json` will override this configuration.
|
||||
|
||||
```yaml
|
||||
// .yarnrc.yml
|
||||
npmRegistryServer: "http://localhost:4873"
|
||||
|
||||
unsafeHttpWhitelist:
|
||||
- localhost
|
||||
```
|
||||
|
||||
> `unsafeHttpWhitelist` is only need it if you don't use `https` with a valid certificate.
|
||||
|
||||
Using scopes is also possible and more segmented, you can define a token peer scope if is required.
|
||||
|
||||
```
|
||||
npmRegistries:
|
||||
"https://registry.myverdaccio.org":
|
||||
npmAlwaysAuth: true
|
||||
npmAuthToken: <TOKEN>
|
||||
npmScopes:
|
||||
my-company:
|
||||
npmRegistryServer: https://registry.myverdaccio.org
|
||||
npmPublishRegistry: https://registry.myverdaccio.org
|
||||
```
|
||||
|
||||
for logging via CLi use:
|
||||
|
||||
```
|
||||
yarn npm login --scope my-company
|
||||
```
|
||||
|
||||
### pnpm {#pnpm}
|
||||
|
||||
> This includes 4.x and 5.x series.
|
||||
|
||||
`pnpm` recognize by default the configuration at `.npmrc` and also the `--registry` value, there is no difference in the implementation.
|
||||
* [npm](setup-npm.md)
|
||||
* [yarn](setup-yarn.md)
|
||||
* [pnpm](setup-pnpm.md)
|
||||
|
||||
@ -91,7 +91,7 @@ Or a `publishConfig` in your `package.json`
|
||||
}
|
||||
```
|
||||
|
||||
For alternative configurations, please read the [Using a privare registry](cli-registry.md) section.
|
||||
For alternative configurations, please read the [Using a private registry](cli-registry.md) section.
|
||||
|
||||
## Create Your Own Private NPM Package Tutorial {#create-your-own-private-npm-package-tutorial}
|
||||
|
||||
|
||||
103
website/docs/setup-npm.md
Normal file
103
website/docs/setup-npm.md
Normal file
@ -0,0 +1,103 @@
|
||||
---
|
||||
id: setup-npm
|
||||
title: "npm"
|
||||
---
|
||||
|
||||
# npm {#npm}
|
||||
|
||||
The minimum supported NPM version is 5.
|
||||
|
||||
## Using Verdaccio for all my projects (recommended)
|
||||
|
||||
To set the registry for all your local projects in any terminal window run:
|
||||
|
||||
```bash
|
||||
npm set registry http://localhost:4873/
|
||||
```
|
||||
This will set the registry for your operational system user and you can find it on the file `~/.npmrc`.
|
||||
|
||||
## Using Verdaccio only to a specific project
|
||||
|
||||
To set this value for a specific project open its root folder on a terminal window and run:
|
||||
```bash
|
||||
npm set registry http://localhost:4873/ --location project
|
||||
```
|
||||
This will set the registry in a `.npmrc` file in your project root directory.
|
||||
|
||||
## Using Verdaccio only on specific commands
|
||||
|
||||
If you want one single use append `--registry http://localhost:4873/` to the required command.
|
||||
Some examples:
|
||||
|
||||
```bash
|
||||
npm ci --registry http://localhost:4873
|
||||
npm install --registry http://localhost:4873
|
||||
npm install lodash --registry http://localhost:4873
|
||||
```
|
||||
|
||||
## How to prevent your package from being published in other registries
|
||||
|
||||
If you only want to publish your package to Verdaccio but keep installing from other registries you can setup the `publishConfig` in your `package.json` as [described in the official documentation](https://docs.npmjs.com/cli/v8/using-npm/registry#how-can-i-prevent-my-package-from-being-published-in-the-official-registry).
|
||||
|
||||
```json
|
||||
{
|
||||
"publishConfig": {
|
||||
"registry": "http://localhost:4873"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### npm does not save authToken when authenticating to Verdaccio
|
||||
|
||||
If you are using either `npm@5.4.x` or `npm@5.5.x`, there are [known issues with tokens](https://github.com/verdaccio/verdaccio/issues/509#issuecomment-359193762), please upgrade to either `6.x` or downgrade to `npm@5.3.0`.
|
||||
|
||||
### SSL and certificates {#ssl-and-certificates}
|
||||
|
||||
When using Verdaccio under SSL without a valid certificate, defining `strict-ssl` in your config file is required otherwise you will get `SSL Error: SELF_SIGNED_CERT_IN_CHAIN` errors.
|
||||
|
||||
`npm` does not support [invalid certificates anymore](https://blog.npmjs.org/post/78085451721/npms-self-signed-certificate-is-no-more) since 2014.
|
||||
|
||||
```bash
|
||||
npm config set ca ""
|
||||
npm config set strict-ssl false
|
||||
```
|
||||
|
||||
### Mixed registries in lockefile (npm v7+)
|
||||
|
||||
Since version 7 npm got more strict with the introduction of `lockfileVersion: 2`. If you have mixed `resolved` fields in your lockfile, for instance, having this in your lockfile:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "npm7",
|
||||
"version": "1.0.0",
|
||||
"lockfileVersion": 2,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"version": "1.0.0",
|
||||
"license": "ISC",
|
||||
"dependencies": {
|
||||
"lodash": "4.17.20",
|
||||
"underscore": "^1.11.0"
|
||||
}
|
||||
},
|
||||
..... // removed for simplicity
|
||||
},
|
||||
"dependencies": {
|
||||
"lodash": {
|
||||
"version": "4.17.20",
|
||||
"resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz",
|
||||
"integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA=="
|
||||
},
|
||||
"underscore": {
|
||||
"version": "1.11.0",
|
||||
"resolved": "http://localhost:4873/underscore/-/underscore-1.11.0.tgz",
|
||||
"integrity": "sha512-xY96SsN3NA461qIRKZ/+qox37YXPtSBswMGfiNptr+wrt6ds4HaMw23TP612fEyGekRE6LNRiLYr/aqbHXNedw=="
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Either running `npm i --registry https://registry.npmjs.org` or using `.npmrc` will fail your installation.
|
||||
11
website/docs/setup-pnpm.md
Normal file
11
website/docs/setup-pnpm.md
Normal file
@ -0,0 +1,11 @@
|
||||
---
|
||||
id: setup-pnpm
|
||||
title: "pnpm"
|
||||
---
|
||||
|
||||
### pnpm {#pnpm}
|
||||
|
||||
> This includes 4.x and 5.x series.
|
||||
|
||||
`pnpm` recognize by default the configuration at `.npmrc` and also the `--registry` value.
|
||||
This means that you can follow the same commands described in [npm](setup-npm.md) replacing `npm` by `pnpm`.
|
||||
64
website/docs/setup-yarn.md
Normal file
64
website/docs/setup-yarn.md
Normal file
@ -0,0 +1,64 @@
|
||||
---
|
||||
id: setup-yarn
|
||||
title: "yarn"
|
||||
---
|
||||
|
||||
# yarn {#yarn}
|
||||
|
||||
#### Yarn (1.x) {#yarn-1x}
|
||||
|
||||
> Be aware npm configurations are valid on the classic version
|
||||
|
||||
The classic version is able to regonize the `.npmrc` file, but also provides their own configuration file named `.yarnrc`.
|
||||
|
||||
To set up a registry, create a file and define a registry.
|
||||
|
||||
```
|
||||
// .yarnrc
|
||||
registry "http://localhost:4873"
|
||||
```
|
||||
|
||||
By using this version you should enable `always-auth` in your configuration running:
|
||||
|
||||
```
|
||||
npm config set always-auth true
|
||||
```
|
||||
|
||||
`yarn@1.x` does not send the authorization header on `yarn install` if your packages requires authentication, by enabling `always-auth` will force yarn do it on each request.
|
||||
|
||||
#### Yarn Berry (>=2.x) {#yarn-berry-2x}
|
||||
|
||||
> Yarn berry does not recognize `--registry` or `.npmrc` file anymore.
|
||||
|
||||
For defining a registry you must use the `.yarnrc.yml` located in the root of your project or global configuration.
|
||||
|
||||
When you publish a package the `npmRegistryServer` must be used. Keep in mind the `publishConfig.registry` in the `package.json` will override this configuration.
|
||||
|
||||
```yaml
|
||||
// .yarnrc.yml
|
||||
npmRegistryServer: "http://localhost:4873"
|
||||
|
||||
unsafeHttpWhitelist:
|
||||
- localhost
|
||||
```
|
||||
|
||||
> `unsafeHttpWhitelist` is only need it if you don't use `https` with a valid certificate.
|
||||
|
||||
Using scopes is also possible and more segmented, you can define a token peer scope if is required.
|
||||
|
||||
```
|
||||
npmRegistries:
|
||||
"https://registry.myverdaccio.org":
|
||||
npmAlwaysAuth: true
|
||||
npmAuthToken: <TOKEN>
|
||||
npmScopes:
|
||||
my-company:
|
||||
npmRegistryServer: https://registry.myverdaccio.org
|
||||
npmPublishRegistry: https://registry.myverdaccio.org
|
||||
```
|
||||
|
||||
for logging via CLi use:
|
||||
|
||||
```
|
||||
yarn npm login --scope my-company
|
||||
```
|
||||
@ -20,7 +20,11 @@ module.exports = {
|
||||
"what-is-verdaccio",
|
||||
"installation",
|
||||
"cli",
|
||||
"cli-registry",
|
||||
{
|
||||
type: "category",
|
||||
label: "Setting up Verdaccio",
|
||||
items: ["cli-registry", "setup-npm", "setup-yarn", "setup-pnpm"]
|
||||
},
|
||||
"who-is-using",
|
||||
"best",
|
||||
"docker",
|
||||
|
||||
Loading…
Reference in New Issue
Block a user