Salta al contenuto principale
Versione: Successivo

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.

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.

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:
    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).

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 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. This can be overridden by setting this value to true.

publish:
  allow_offline: false

Checking Package Ownership​

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

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](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​

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