Salta al contenuto principale
Versione: 6.x

File di configurazione

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

La prima volta in assoluto che si esegue verdaccio viene creato un file di configurazione config.yaml predefinito.

Configurazione Predefinita​

La configurazione predefinita dispone del supporto per pacchetti ** scoped** e permette a qualsiasi utente di accedere a tutti i pacchetti ma solo agli utenti autenticati di pubblicare.

storage: ./storage
auth:
  htpasswd:
    file: ./htpasswd
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    proxy: npmjs
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

Security​

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 (aes192) 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
    migrateToSecureLegacySignature: true # will generate a new secret token if the length is 64 characters

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:
    legacy: true
    migrateToSecureLegacySignature: true # will generate a new secret token if the length is 64 characters
    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).

You can specify HTTP/1.1 server keep alive timeout in seconds for incoming connections. 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 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​

Di default, Verdaccio non ti consente di pubblicare i pacchetti quando il client è offline. Ciò è sovrascrivibile impostando questo valore a true.

publish:
  allow_offline: false
A partire da: verdaccio@2.3.6 paragrafo #223

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.

La logica interna costruisce correttamente l'URL pubblico, convalida l'intestazione host e l'url_prefix mal costruito.

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

Leggi di più su VERDACCIO_PUBLIC_URL sulla pagina delle variabili ambientali.

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](https://github.com/verdaccio/verdaccio/releases/tag/v5.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​

I proxy sono server HTTP a scopo speciale, progettati per trasferire i dati da server remoti ai client locali.

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​

pericolo

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();