0
# Configuration Management
1

2
Configuration parsing, validation, and management utilities for Verdaccio server setup and customization.
3

4
## Capabilities
5

6
### Configuration File Parsing
7

8
Parse and validate Verdaccio configuration files with automatic path resolution.
9

10
```typescript { .api }
11
/**
12
 * Parse Verdaccio configuration file with validation and defaults
13
 * @param configPath - Absolute path to configuration file (YAML format)
14
 * @returns Parsed and validated configuration object
15
 * @throws Error if file doesn't exist or contains invalid YAML
16
 */
17
function parseConfigFile(configPath: string): any;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { parseConfigFile } from "verdaccio";
24

25
// Parse configuration file
26
const config = parseConfigFile("/path/to/config.yaml");
27

28
// Configuration is ready to use
29
const server = await runServer(config);
30
```
31

32
### Configuration Builder
33

34
Utility class for programmatically building Verdaccio configurations.
35

36
```typescript { .api }
37
/**
38
 * Configuration builder utility class for programmatic config creation
39
 */
40
class ConfigBuilder {
41
  /**
42
   * Build configuration with validation and defaults
43
   */
44
  static build(options: any): any;
45
}
46
```
47

48
### Configuration File Discovery
49

50
Locate Verdaccio configuration files using standard search paths.
51

52
```typescript { .api }
53
/**
54
 * Find configuration file using standard search locations
55
 * @param customPath - Optional custom configuration file path
56
 * @returns Absolute path to configuration file
57
 * @throws Error if no configuration file found
58
 */
59
function findConfigFile(customPath?: string): string;
60
```
61

62
**Search order:**
63
1. Custom path (if provided)
64
2. `./config.yaml` (current directory)
65
3. `~/.config/verdaccio/config.yaml` (user config)
66
4. `/etc/verdaccio/config.yaml` (system config)
67

68
## Configuration Structure
69

70
### Core Configuration Options
71

72
```yaml
73
# Storage location for packages and metadata
74
storage: ./storage
75

76
# Authentication providers
77
auth:
78
  htpasswd:
79
    file: ./htpasswd
80
    max_users: 1000
81

82
# Upstream registry links
83
uplinks:
84
  npmjs:
85
    url: https://registry.npmjs.org/
86
    timeout: 30s
87
    max_fails: 2
88

89
# Package access control
90
packages:
91
  '@private/*':
92
    access: $authenticated
93
    publish: $authenticated
94
  '**':
95
    access: $all
96
    publish: $authenticated
97
    proxy: npmjs
98

99
# Server settings
100
listen: 0.0.0.0:4873
101

102
# Web interface
103
web:
104
  enable: true
105
  title: Verdaccio
106

107
# Logging configuration
108
logs:
109
  - { type: stdout, format: pretty, level: info }
110
```
111

112
### Storage Configuration
113

114
```typescript { .api }
115
interface StorageConfig {
116
  /** Storage directory path */
117
  storage: string;
118
  /** Plugin configuration for custom storage */
119
  store?: {
120
    [pluginName: string]: any;
121
  };
122
}
123
```
124

125
### Authentication Configuration
126

127
```typescript { .api }
128
interface AuthConfig {
129
  /** Built-in htpasswd authentication */
130
  htpasswd?: {
131
    file: string;
132
    max_users?: number;
133
  };
134
  /** Plugin-based authentication */
135
  [pluginName: string]: any;
136
}
137
```
138

139
### Uplinks Configuration
140

141
```typescript { .api }
142
interface UplinksConfig {
143
  [uplinkName: string]: {
144
    url: string;
145
    timeout?: string;
146
    max_fails?: number;
147
    fail_timeout?: string;
148
    headers?: { [key: string]: string };
149
    ca?: string;
150
    cert?: string;
151
    key?: string;
152
    strict_ssl?: boolean;
153
  };
154
}
155
```
156

157
### Packages Configuration
158

159
```typescript { .api }
160
interface PackagesConfig {
161
  [pattern: string]: {
162
    access: string | string[];
163
    publish: string | string[];
164
    proxy?: string | string[];
165
    storage?: string;
166
  };
167
}
168
```
169

170
### Server Configuration
171

172
```typescript { .api }
173
interface ServerConfig {
174
  /** Listen address and port */
175
  listen?: string | string[];
176
  /** HTTPS configuration */
177
  https?: {
178
    key?: string;
179
    cert?: string;
180
    ca?: string;
181
    pfx?: string;
182
    passphrase?: string;
183
  };
184
  /** Keep-alive timeout in seconds */
185
  keepAliveTimeout?: number;
186
  /** Trust proxy headers */
187
  trustProxy?: boolean | string | string[];
188
}
189
```
190

191
### Web Interface Configuration
192

193
```typescript { .api }
194
interface WebConfig {
195
  /** Enable web interface */
196
  enable?: boolean;
197
  /** Web interface title */
198
  title?: string;
199
  /** Custom logo URL */
200
  logo?: string;
201
  /** Primary color theme */
202
  primary_color?: string;
203
  /** Login functionality */
204
  login?: boolean;
205
  /** Package scope filters */
206
  scope?: string;
207
}
208
```
209

210
### Logging Configuration
211

212
```typescript { .api }
213
interface LogConfig {
214
  type: 'stdout' | 'stderr' | 'file';
215
  format: 'pretty' | 'pretty-timestamped' | 'json';
216
  level: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
217
  path?: string; // for file type
218
}
219
```
220

221
## Configuration Validation
222

223
### Required Fields
224
- `storage`: Must be a valid directory path
225
- `auth`: At least one authentication method
226
- `packages`: At least one package pattern
227

228
### Optional Fields
229
- `uplinks`: Defaults to npmjs.org if not specified
230
- `listen`: Defaults to `localhost:4873`
231
- `web`: Defaults to enabled
232
- `logs`: Defaults to pretty stdout logging
233

234
### Environment Variable Substitution
235

236
Configuration files support environment variable substitution:
237

238
```yaml
239
storage: ${VERDACCIO_STORAGE_PATH:-./storage}
240
listen: ${VERDACCIO_PORT:-4873}
241

242
auth:
243
  htpasswd:
244
    file: ${VERDACCIO_HTPASSWD_FILE:-./htpasswd}
245
```
246

247
## Migration and Compatibility
248

249
### Configuration Migration
250
- V5 to V6 configuration migration utilities
251
- Automatic handling of deprecated configuration options
252
- Warning messages for outdated configuration patterns
253

254
### Backward Compatibility
255
- Support for legacy configuration formats
256
- Graceful handling of removed options
257
- Migration guides for major version upgrades
258

259
## Configuration Examples
260

261
### Minimal Configuration
262
```yaml
263
storage: ./storage
264
auth:
265
  htpasswd:
266
    file: ./htpasswd
267
packages:
268
  '**':
269
    access: $all
270
    publish: $authenticated
271
```
272

273
### Enterprise Configuration
274
```yaml
275
storage: /var/lib/verdaccio/storage
276

277
auth:
278
  ldap:
279
    url: ldap://ldap.company.com
280
    baseDN: 'ou=people,dc=company,dc=com'
281

282
uplinks:
283
  npmjs:
284
    url: https://registry.npmjs.org/
285
  internal:
286
    url: https://internal-registry.company.com/
287

288
packages:
289
  '@company/*':
290
    access: $authenticated
291
    publish: $authenticated
292
    storage: company-packages
293
  '**':
294
    access: $all
295
    publish: $authenticated
296
    proxy: npmjs
297

298
listen: 0.0.0.0:4873
299

300
https:
301
  key: /etc/ssl/private/verdaccio.key
302
  cert: /etc/ssl/certs/verdaccio.crt
303

304
web:
305
  title: Company NPM Registry
306
  logo: https://company.com/logo.png
307
  primary_color: "#4CAF50"
308

309
logs:
310
  - { type: file, path: /var/log/verdaccio/verdaccio.log, level: info }
311
```