File di configurazione

Questo file è il fondamento di verdaccio nel quale è possibile modificare il comportamento predefinito, attivare i plugin ed estendere le funzionalità.

A default configuration file config.yaml is created the very first time you run verdaccio. You can find the most recent version of the default configuration here.

Configurazione Predefinita

The default configuration has support for scoped packages and allows any user to access all packages, but only authenticated users to publish or unpublish.

storage: ./storage

auth:
  htpasswd:
    file: ./htpasswd

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs

middlewares:
  audit:
    enabled: true

log:
  type: stdout
  format: pretty
  level: http

Sezioni

Le sezioni seguenti spiegano cosa significa ogni proprietà e le diverse opzioni possibili.

Archiviazione

È il percorso di archiviazione predefinito. Verdaccio è di default basato sul file locale di sistema.

storage: ./storage

Rilasciato alla v5.6.0: La variabile ambientale VERDACCIO_STORAGE_PATH è utilizzabile per sostituire la posizione dell'archiviazione (solo per l'archiviazione predefinita, non si applica ai plugin a meno che non sono implementati indipendentemente).

Il database di `.verdaccio-db`

The tiny database is used to store private packages published by the user. The database is based on a JSON file that contains the list of private packages published and the secret token used for the token signature. It is created automatically when starting the application for the first time.

The location of the database is based on the config.yaml folder location, for instance:

If the config.yaml is located in /some_local_path/config.yaml, the database will be created in /some_local_path/storage/.verdaccio-db.

info

For users who have been using Verdaccio for an extended period and the .verdaccio-db file already exist the secret may be 64 characters long. However, for newer installations, the length will be generated as 32 characters long.

If the secret length is 64 characters long:

For users running Verdaccio 5.x on Node.js 22 or higher, the application will fail to start if the secret length is not 32 characters long.
For users running Verdaccio 5.x on Node.js 21 or lower, the application will start, but it will display a deprecation warning at the console.

How to upgrade the token secret at the storage?

⚠️ If the secret is updated will invalidate all previous generated tokens.

Option 1: Manually

Go to the storage location and edit manually the secret to be 32 characters long.

Option 2: Automatically (since v5.31.0)

The migrateToSecureLegacySignature property is used to generate a new secret token if the length is 64 characters.

security:
  api:
    migrateToSecureLegacySignature: true

The token will be automatically updated to 32 characters long and the application will start without any issues. The property won't have any other effect on the application and could be removed after the secret is updated.

The .verdaccio-db file database is only available if user does not use a custom storage, by default verdaccio uses a tiny database to store private packages the storage property is defined in the config.yaml file. The location might change based on your operating system. Read the CLI section for more details about the location of files.

La struttura del database si basa nel file JSON, per esempio:

{
  "list": ["package1", "@scope/pkg2"],
  "secret": "secret_token_32_characters_long"
}

list: è un insieme con l'elenco dei pacchetti privati pubblicati; qualsiasi elemento su questo elenco è considerato come pubblicato dall'utente.
secret: The secret field is used for the token signature and verification, either for JWT or legacy token signature.

Estensioni

È la posizione della cartella del plugin. Utile per le distribuzioni basate su Docker/Kubernetes.

plugins: ./plugins

Autenticazione

Qui viene effettuata la configurazione dell'autenticazione. L'autenticazione predefinita si basa su httpasswd ed è integrata. Puoi modificare questo comportamento tramite i plugin. Per ulteriori informazioni su questa sezione, consulta la pagina d'autenticazione.

auth:
  htpasswd:
    file: ./htpasswd
    max_users: 1000

Firma del token

The default token signature is based on the Advanced Encryption Standard (AES) with the algorithm aes-256-ctr, known as legacy. È importante notare che i token ereditari non sono progettati per scadere. Se la funzionalità di scadenza è necessaria, si consiglia di utilizzare JSON Web Tokens (JWT) al suo posto.

Sicurezza

The security block permits customization of the token signature with two options. The configuration is divided into two sections, api and web. When using JWT on api, it must be defined; otherwise, the legacy token signature (aes-256-ctr) will be utilized.

How to the token is generated?

The token signature requires a secret token generated by custom plugin that creates the .verdaccio-db database or in case a custom storage is used, the secret token is fetched from the plugin implementation itself. In any case the secret token is required to start the application.

Legacy Token Signature

The legacy property is used to enable the legacy token signature. By default is enabled. The legacy feature only applies to the API, the web UI uses JWT by default.

info

In 5.x versions using Node.js 21 or lower, there will see the warning [DEP0106] DeprecationWarning: crypto.createDecipher is deprecated. printed in your terminal. Questo avviso indica che Node.js ha deprecato una funzione utilizzata dalla firma ereditaria.

If verdaccio runs on Node.js 22 or higher, you will not see this warning since a new modern legacy signature has been implemented.

The migrateToSecureLegacySignature property is only available for versions higher than 5.31.0 and is false by default.

security:
  api:
    legacy: true # by default is true even if this section is not defined

JWT Token Signature

To enable a new JWT (JSON Web Tokens) signature, the jwt block needs to be added to the api section; jwt is utilized by default in web.

By using the JWT signature is also possible to customize the signature and the token verification with your own properties.

security:
  api:
    jwt:
      sign:
        expiresIn: 29d
      verify:
        someProp: [value]
  web:
    sign:
      expiresIn: 1h # 1 hour by default
    verify:
      someProp: [value]

Server

Una serie di proprietà per modificare il comportamento dell'applicazione del server, nello specifico, l'API (Express.js).

Puoi specificare il timeout di attività del server HTTP/1.1 in secondi per le connessioni in entrata. Un valore di 0 fa comportare il server http similmente alle versioni di Node.js precedenti alla 8.0.0, che non aveva un timoeut di attività. SOLUZIONE: Tramite la data configurazione, puoi risolvere il seguente problema: https://github.com/verdaccio/verdaccio/issues/301. Impostalo a 0 nel caso in cui 60 non sia abbastanza.

server:
  keepAliveTimeout: 60

Web UI

Questa proprietà ti consente di modificare l'aspetto dell'UI web. Per ulteriori informazioni su questa sezione, leggi la pagina sull'UI Web.

web:
  enable: true
  title: Verdaccio
  logo: logo.png
  scope:

Uplink

Uplink aggiunge la capacità di recuperare i pacchetti da registri remoti, quando non sono localmente disponibili. Per ulteriori informazioni su questa sezione, leggi la pagina sugli uplink.

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

Pacchetti

Questa sezione ti consente di controllare come sono acceduti i pacchetti. Per ulteriori informazioni su questa sezione, leggi la pagina sui pacchetti.

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs

Impostazioni Avanzate

Pubblicazione offline

By default Verdaccio does not allow you to publish packages when the client is offline. This can be overridden by setting this value to true.

publish:
  allow_offline: false

A partire da: verdaccio@2.3.6 paragrafo #223

Checking Package Ownership

info

Only available on experimental versions >8.x and higher

By default, package access defines who is allowed to publish and unpublish packages. By setting check_owners to true, only package owners are allowed to make changes to a package. The first owner of a package is the user who published the first version. Further owners can be added or removed using npm owner. You can find the list of current owners using npm owner list or by checking the package manifest under maintainers.

publish:
  check_owners: false

Keep Readmes

info

Only available on experimental versions >8.x and higher

By default, Verdaccio stores only the readme markdown of the latest version for each package. Setting keep_readmes to 'tagged' keeps the readmes of versions with dist-tags (for example, latest, next, and major branches). Using the 'all' setting will retain the complete history of readme versions. Note that 'all' can significantly increase the required storage space for packages published to Verdaccio!

publish:
  keep_readmes: 'tagged'

URL Prefix

Il prefisso è inteso per l'utilizzo quando il server è eseguito dietro al proxy e non funzionerà adeguatamente se è utilizzato senza un proxy inverso; consulta la pagina di configurazione del proxy inverso per ulteriori dettagli.

The internal logic builds correctly the public url, validates the host header and bad shaped url_prefix.

es: url_prefix: /verdaccio, url_prefix: verdaccio/, url_prefix: verdaccio sarebbe /verdaccio/

url_prefix: /verdaccio/

Il nuovo VERDACCIO_PUBLIC_URL è inteso all'uso dietro proxy, questa variabile sarà usata per:

Usata come percorso di base per servire risorse dell'UI come (js, favicon, etc.)
Usata alla restituzione del percorso di base dist dei meta-dati
Ignora le intestazioni host e X-Forwarded-Proto
Se url_prefix è definito sarà messo in attesa alla variabile env.

VERDACCIO_PUBLIC_URL='https://somedomain.org';
url_prefix: '/my_prefix'

// url -> https://somedomain.org/my_prefix/

VERDACCIO_PUBLIC_URL='https://somedomain.org';
url_prefix: '/'

// url -> https://somedomain.org/

VERDACCIO_PUBLIC_URL='https://somedomain.org/first_prefix';
url_prefix: '/second_prefix'

// url -> https://somedomain.org/second_prefix/'

User Agent

A partire da: verdaccio@5.4.0

L'agente dell'utente è disabilitato di default, in cambio, il client dell'agente dell'utente (gestore di pacchetti, browser, etc...) è aggirato al remoto. Per consentire il comportamento precedente, utilizza valori booleani.

user_agent: true
user_agent: false
user_agent: 'custom user agent'

Limite di frequenza dell'utente

Dalla: verdaccio@5.4.0

Add default rate limit to user endpoints, npm token, npm profile, npm login/adduser and login website to 100 request peer 15 min, customizable via:

userRateLimit:
  windowMs: 50000
  max: 1000

Un'ulteriore configurazione è possibile (soltaanto dei flag della funzionalità), tramite la documentazione sui middleware.

Dimensione massima del corpo

Di default, la dimensione massima del corpo per un documento JSON è di 10mb; se riscontri degli errori che dichiarano che "l'entità richiesta è troppo grande", puoi incrementare tale valore.

max_body_size: 10mb

Porta d'ascolto

verdaccio è eseguito di default sulla porta 4873. Puoi modificare la porta tramite la CLI o nel file di configurazione. Le seguenti opzioni sono valide:

listen:
# - localhost:4873            # valore predefinito
# - http://localhost:4873     # stessa cosa
# - 0.0.0.0:4873              # ascolta su tutti gli indirizzi (INADDR_ANY)
# - https://example.org:4873  # se desideri utilizzare https
# - "[::1]:4873"                # ipv6
# - unix:/tmp/verdaccio.sock    # socket di unix

HTTPS

Per abilitare https su verdaccio, basta impostare il flag listen con il protocollo https://. Per ulteriori informazioni su questa sezione, leggi la pagina su SSL.

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. You can define a HTTP or HTTPS proxy in the main configuration or separately for each uplink. The definition for uplinks have higher priority.

nota

The proxy configuration key (http_proxy or https_proxy) has to match the protocol of the uplink URL!

For example, to use a proxy for npm i.e. https://registry.npmjs.com, then you have to use https_proxy in your configuration to specify you proxy URL (no matter if the proxy uses http or https).

uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    https_proxy: http://my.proxy.local/

http_proxy e https_proxy

Se hai un proxy nella tua rete, puoi impostare un'intestazione X-Forwarded-For, utilizzando le seguenti proprietà:

http_proxy: http://something.local/
https_proxy: https://something.local/

no_proxy

Questa variabile dovrebbe contenere un elenco separato da virgole delle estensioni del dominio, per le quali il proxy non dovrebbe essere utilizzato.

no_proxy: localhost,127.0.0.1

Notifiche

Abilitare le notifiche agli strumenti di terze parti è abbastanza facile tramite i webhook. Per ulteriori informazioni su questa sezione, leggi la pagina sulle notifiche.

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"}'

Per impostazioni di configurazione più dettagliate, sei pregato di controllare il codice sorgente.

Registratore

warning

Dalla v5.22.0, la proprietà del registratore viene rinominata in logs; log è ancora compatibile, ma mostrerà un avviso

Sono supportati due tipi di registratori, puoi sceglierne soltanto uno dei due:

output della console (il predefinito)

log: { type: stdout, format: pretty, level: http }

output del file

log: { type: file, path: verdaccio.log, level: info }

Per le informazioni complete, consulta qui: Features/logger

Controllo

Dalla: verdaccio@3.0.0

npm audit è un nuovo comando rilasciato con npm 6.x. Verdaccio include un plugin middleware integrato per gestire questo comando.

Se hai una nuova installazione, è predefinito, altrimenti devi aggiungere le seguenti proprietà al tuo file di configurazione

middlewares:
  audit:
    enabled: true
    # timeout: 10000

Esperimenti

Questa release include una nuova proprietà detta experiments, posizionabile nel config.yaml ed è completamente facoltativa.

Vogliamo poter consegnare nuove funzionalità senza influenzare gli ambienti di produzione. Questo flag ci consente di aggiungere nuove funzionalità e ricevere feedback dalla community che decide di utilizzarle.

Le funzionalità sotto questo flag potrebbero non essere stabili o essere rimosse nelle versioni future.

Ecco un esempio:

experiments:
  changePassword: false

Per disabilitare l'avviso degli esperimenti nella console, devi commentare l'intera sezione degli esperimenti.

Config Builder API

Dopo la versione v5.23.1, la nuova API del costruttore della configurazione avanzata è disponibile. L'API è un metodo flessibile per generare programmaticamente degli output di configurazione in JSON o YAML, utilizzando il modello del costruttore, ad esempio:

import { ConfigBuilder } from 'verdaccio';

const config = ConfigBuilder.build();
config
  .addUplink('upstream', { url: 'https://registry.upstream.local' })
  .addUplink('upstream2', { url: 'https://registry.upstream2.local' })
  .addPackageAccess('upstream/*', {
    access: 'public',
    publish: 'foo, bar',
    unpublish: 'foo, bar',
    proxy: 'some',
  })
  .addLogger({ level: 'info', type: 'stdout', format: 'json' })
  .addStorage('/tmp/verdaccio')
  .addSecurity({ api: { legacy: true } });

// genera oggetto JSON come output
config.getConfig();

// genera output come yaml
config.getAsYaml();

Configurazione Predefinita​

Sezioni​

Archiviazione​

Il database di .verdaccio-db​

How to upgrade the token secret at the storage?​

Option 1: Manually​

Option 2: Automatically (since v5.31.0)​

Estensioni​

Autenticazione​

Firma del token​

Sicurezza​

How to the token is generated?​

Legacy Token Signature​

JWT Token Signature​

Server​

Web UI​

Uplink​

Pacchetti​

Impostazioni Avanzate​

Pubblicazione offline​

Checking Package Ownership​

Keep Readmes​

URL Prefix​

User Agent​

Limite di frequenza dell'utente​

Dimensione massima del corpo​

Porta d'ascolto​

HTTPS​

Proxy​

http_proxy e https_proxy​

no_proxy​

Notifiche​

Registratore​

output della console (il predefinito)​

output del file​

Controllo​

Esperimenti​

Config Builder API​

Configurazione Predefinita

Sezioni

Archiviazione

Il database di `.verdaccio-db`

How to upgrade the token secret at the storage?

Option 1: Manually

Option 2: Automatically (since v5.31.0)

Estensioni

Autenticazione

Firma del token

Sicurezza

How to the token is generated?

Legacy Token Signature

JWT Token Signature

Server

Web UI

Uplink

Pacchetti

Impostazioni Avanzate

Pubblicazione offline

Checking Package Ownership

Keep Readmes

URL Prefix

User Agent

Limite di frequenza dell'utente

Dimensione massima del corpo

Porta d'ascolto

HTTPS

Proxy

http_proxy e https_proxy

no_proxy

Notifiche

Registratore

output della console (il predefinito)

output del file

Controllo

Esperimenti

Config Builder API