0
# Server Management
1

2
Core server creation and lifecycle management for running Verdaccio programmatically or via CLI.
3

4
## Capabilities
5

6
### Primary Server Factory
7

8
Creates a Verdaccio server instance for programmatic usage with flexible configuration options.
9

10
```typescript { .api }
11
/**
12
 * Primary server factory function for programmatic usage
13
 * @param config - Configuration file path (string) or undefined for default configuration
14
 * @returns Promise resolving to HTTP/HTTPS server instance ready to listen
15
 */
16
function runServer(config?: string): Promise<any>;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { runServer } from "verdaccio";
23

24
// Default configuration (looks for config.yaml in current directory)
25
const server = await runServer();
26
server.listen(4873, () => {
27
  console.log("Verdaccio started on http://localhost:4873");
28
});
29

30
// Custom configuration file
31
const serverFromFile = await runServer("./custom-config.yaml");
32
serverFromFile.listen(5000);
33

34
// Absolute path to configuration
35
const serverFromAbsPath = await runServer("/etc/verdaccio/config.yaml");
36
serverFromAbsPath.listen(4873);
37
```
38

39
### Legacy Server Bootstrap
40

41
Legacy function for starting Verdaccio server (deprecated in favor of runServer).
42

43
```typescript { .api }
44
/**
45
 * Legacy server bootstrap function (deprecated, use runServer instead)
46
 * @param config - Configuration object
47
 * @param cliListen - Listen address from CLI arguments
48
 * @param configPath - Path to configuration file
49
 * @param pkgVersion - Package version string
50
 * @param pkgName - Package name string
51
 * @param callback - Callback function called for each listen address
52
 */
53
function startVerdaccio(
54
  config: any,
55
  cliListen: string,
56
  configPath: string,
57
  pkgVersion: string,
58
  pkgName: string,
59
  callback: Callback
60
): void;
61

62
interface Callback {
63
  (webServer: any, addr: any, pkgName: string, pkgVersion: string): void;
64
}
65
```
66

67
### Default Listen Callback
68

69
Default callback implementation for server listening (used with legacy startVerdaccio).
70

71
```typescript { .api }
72
/**
73
 * Default callback implementation for server listening (deprecated)
74
 * @param webServer - Express application instance
75
 * @param addr - Listen address configuration
76
 * @param pkgName - Package name
77
 * @param pkgVersion - Package version
78
 */
79
function listenDefaultCallback(
80
  webServer: Application,
81
  addr: any,
82
  pkgName: string,
83
  pkgVersion: string
84
): void;
85
```
86

87
### Server Factory Creation
88

89
Low-level server factory for creating HTTP/HTTPS server instances.
90

91
```typescript { .api }
92
/**
93
 * Create HTTP/HTTPS server instance based on configuration
94
 * @param config - Verdaccio configuration object
95
 * @param addr - Address configuration object
96
 * @param app - Express application instance
97
 * @returns HTTP or HTTPS server instance
98
 */
99
function createServerFactory(config: Config, addr: any, app: any): any;
100
```
101

102
### Experiments Display
103

104
Utility function for displaying experimental features information.
105

106
```typescript { .api }
107
/**
108
 * Display information about enabled experimental features
109
 * @param flags - Experimental features configuration object
110
 */
111
function displayExperimentsInfoBox(flags: any): void;
112
```
113

114
## Error Handling
115

116
Server management functions handle various error conditions:
117

118
- **Configuration errors**: Invalid or missing configuration files
119
- **Port binding errors**: Port already in use or permission issues
120
- **HTTPS certificate errors**: Invalid certificate files or configuration
121
- **Storage initialization errors**: Storage directory creation or permission issues
122

123
All server factory functions will throw descriptive errors for configuration and startup issues.
124

125
## HTTPS Support
126

127
Verdaccio supports HTTPS with two configuration methods:
128

129
1. **Key and Certificate files**:
130
```typescript
131
const server = await runServer({
132
  https: {
133
    key: "/path/to/private.key",
134
    cert: "/path/to/certificate.crt",
135
    ca: "/path/to/ca.crt" // optional
136
  }
137
});
138
```
139

140
2. **PFX certificate**:
141
```typescript
142
const server = await runServer({
143
  https: {
144
    pfx: "/path/to/certificate.pfx",
145
    passphrase: "certificate-password" // optional
146
  }
147
});
148
```
149

150
## Server Configuration
151

152
Key configuration options for server management:
153

154
- `listen`: Host and port binding configuration
155
- `https`: HTTPS certificate configuration
156
- `server.keepAliveTimeout`: Keep-alive timeout in seconds
157
- `server.trustProxy`: Trust proxy headers configuration