Add Windows install types and release channels doc + update map.csv (#21119)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: ilyam8 <ilya@netdata.cloud>
Kanela committed
Oct 17, 2025 at 14:12 UTC
7dd26864f55121fb9e248d5411ee4fddfbf63141
2 files changed
+369
docs/.map/map.csv
+1
@@ -17,6 +17,7 @@ https://github.com/netdata/netdata/edit/master/packaging/makeself/README.md,Stat
17
https://github.com/netdata/netdata/edit/master/docs/learn/switching-install-types.md,Switch Install Types and Release Channels,Published,Netdata Agent/Installation/Linux,
18
https://github.com/netdata/netdata/edit/master/packaging/installer/methods/offline.md,Offline systems,Published,Netdata Agent/Installation/Linux,"Install the Netdata Agent on offline/air gapped systems to benefit from real-time, per-second monitoring without connecting to the internet."
19
https://github.com/netdata/netdata/edit/master/packaging/windows/WINDOWS_INSTALLER.md,Windows,Published,Netdata Agent/Installation,
20
+https://github.com/netdata/netdata/edit/master/docs/install/windows-release-channels.md,Switching Windows Install Types and Release Channels,Published,"Netdata Agent/Installation/Windows/Switching Install Types and Release Channels","Guide to choosing and switching between different Netdata Windows installation methods and release channels"
21
https://github.com/netdata/netdata/edit/master/packaging/docker/README.md,Docker,Published,Netdata Agent/Installation,
22
https://github.com/netdata/netdata/edit/master/packaging/installer/methods/kubernetes.md,Kubernetes,Published,Netdata Agent/Installation,"Deploy Netdata to monitor a Kubernetes cluster to monitor the health, performance, resource utilization, and application metrics of a Kubernetes cluster in real time."
23
https://github.com/netdata/helmchart/edit/master/charts/netdata/README.md,Kubernetes Helm chart reference,Published,Netdata Agent/Installation,
docs/install/windows-release-channels.md
new
+368
@@ -0,0 +1,368 @@
1
+# Switching Netdata Install Types and Release Channels on Windows
2
+
3
+You can switch between different Netdata release channels on Windows based on your needs. This guide covers the process with step-by-step instructions.
4
+
5
+## Understanding Windows Installation Architecture
6
+
7
+Unlike Linux systems where Netdata has multiple install types (native packages, static builds, Docker, etc.), **Windows only has one install type**: the **MSI installer**.
8
+
9
+This simplifies the switching process significantly:
10
+
11
+- No need to determine your "install type" (it's always MSI)
12
+- No complex switching procedures between different installation methods
13
+- MSI handles upgrades automatically
14
+
15
+### Release Channels Available
16
+
17
+| Channel | Download URL | Update Frequency | Recommended For |
18
+|-------------|-----------------------------------------------------------------------------------------|--------------------------|-------------------------------------------------|
19
+| **Stable** | `https://github.com/netdata/netdata/releases/latest/download/netdata-x64.msi` | Major and patch releases | Production systems, most users |
20
+| **Nightly** | `https://github.com/netdata/netdata-nightlies/releases/latest/download/netdata-x64.msi` | Daily builds | Testing, early adopters, bleeding-edge features |
21
+
22
+<details>
23
+<summary>When to Choose Each Channel</summary>
24
+
25
+**Choose Stable Channel If:**
26
+
27
+- You're running production systems
28
+- You need predictable, well-tested releases
29
+- You prefer less frequent updates (major releases only)
30
+- You want maximum stability over cutting-edge features
31
+- You have strict change management processes
32
+
33
+**Choose Nightly Channel If:**
34
+
35
+- You're testing new features before production deployment
36
+- You want immediate bug fixes without waiting for releases
37
+- You're contributing to Netdata development and need latest code
38
+- You want to provide early feedback to the Netdata team
39
+
40
+**Update Frequency**: Stable releases occur every few weeks to months, while Nightly builds are updated daily with every commit to the master branch.
41
+
42
+</details>
43
+
44
+## Data Preservation When Switching Channels
45
+
46
+When switching between release channels on Windows, the MSI installer automatically preserves your important data and configuration.
47
+
48
+**Preserved during channel switches:**
49
+
50
+- Configuration files (`netdata.conf`, collector configs) in `C:\Program Files\Netdata\etc\netdata`
51
+- Historical metrics data
52
+- Alert configurations
53
+- Cloud connection settings (claim token, room assignments)
54
+
55
+**Not preserved (by design):**
56
+
57
+- Temporary cache files
58
+- Log files older than retention period
59
+
60
+:::tip
61
+
62
+Unlike switching between install types on Linux, Windows channel switching does not require manual backup and restore procedures. The MSI installer handles data preservation automatically.
63
+
64
+:::
65
+
66
+## Switching Between Release Channels
67
+
68
+### Method 1: GUI Installation (Recommended)
69
+
70
+<details>
71
+<summary>Switch to Stable Channel</summary>
72
+
73
+1. **Download the Stable MSI:**
74
+ - Go to: `https://github.com/netdata/netdata/releases/latest/download/netdata-x64.msi`
75
+ - Save the file to your Downloads folder
76
+
77
+2. **Run the installer:**
78
+ - Double-click the downloaded `.msi` file
79
+ - Grant Administrator privileges when prompted
80
+ - Follow the installation wizard
81
+
82
+ 
83
+
84
+3. **Verify the installation:**
85
+ - The installer will automatically detect your existing installation
86
+ - Upgrade to the Stable channel
87
+ - Preserve your configuration and data
88
+ - Restart the Netdata service
89
+
90
+</details>
91
+
92
+<br/>
93
+
94
+<details>
95
+<summary>Switch to Nightly Channel</summary>
96
+
97
+1. **Download the Nightly MSI:**
98
+ - Go to: `https://github.com/netdata/netdata-nightlies/releases/latest/download/netdata-x64.msi`
99
+ - Save the file to your Downloads folder
100
+
101
+2. **Run the installer:**
102
+ - Double-click the downloaded `.msi` file
103
+ - Grant Administrator privileges when prompted
104
+ - Follow the installation wizard
105
+
106
+ 
107
+
108
+3. **Verify the installation:**
109
+ - The installer will automatically detect your existing installation
110
+ - Upgrade to the Nightly channel
111
+ - Preserve your configuration and data
112
+ - Restart the Netdata service
113
+
114
+</details>
115
+
116
+### Method 2: PowerShell Installation (Automated)
117
+
118
+:::warning
119
+Silent installation isn't supported on Windows Server versions earlier than 2019 due to TLS compatibility issues.
120
+Use the [GUI installer](#method-1-gui-installation-recommended) instead.
121
+:::
122
+
123
+<details>
124
+<summary>Switch to Stable Channel via PowerShell</summary>
125
+
126
+```powershell
127
+# Run PowerShell as Administrator
128
+$ProgressPreference = 'SilentlyContinue'
129
+Invoke-WebRequest https://github.com/netdata/netdata/releases/latest/download/netdata-x64.msi -OutFile "$env:TEMP\netdata-x64.msi"
130
+msiexec /qn /i "$env:TEMP\netdata-x64.msi" REINSTALL=ALL
131
+```
132
+
133
+</details>
134
+
135
+<br/>
136
+
137
+<details>
138
+<summary>Switch to Nightly Channel via PowerShell</summary>
139
+
140
+```powershell
141
+# Run PowerShell as Administrator
142
+$ProgressPreference = 'SilentlyContinue'
143
+Invoke-WebRequest https://github.com/netdata/netdata-nightlies/releases/latest/download/netdata-x64.msi -OutFile "$env:TEMP\netdata-x64.msi"
144
+msiexec /qn /i "$env:TEMP\netdata-x64.msi" REINSTALL=ALL
145
+```
146
+
147
+</details>
148
+
149
+### Method 3: PowerShell with Cloud Connection Preserved
150
+
151
+<details>
152
+<summary>Switch Channels with Explicit Cloud Settings</summary>
153
+
154
+If you want to ensure your Netdata Cloud connection is maintained during the switch, you can provide your claim token and room IDs explicitly.
155
+
156
+**Get your current cloud settings:**
157
+
158
+```powershell
159
+# Check current cloud configuration
160
+Get-Content "C:\Program Files\Netdata\etc\netdata\cloud.d\cloud.conf"
161
+```
162
+
163
+Look for your `token` and `rooms` values.
164
+
165
+**Switch to Stable with Cloud settings:**
166
+
167
+```powershell
168
+# Run PowerShell as Administrator
169
+$TOKEN = "<YOUR_CLOUD_TOKEN>" # <-- Replace with your Netdata Cloud claim token
170
+$ROOMS = "<YOUR_ROOM_IDS>" # <-- Replace with your comma-separated Room IDs
171
+$ProgressPreference = 'SilentlyContinue'
172
+Invoke-WebRequest https://github.com/netdata/netdata/releases/latest/download/netdata-x64.msi -OutFile "$env:TEMP\netdata-x64.msi"
173
+msiexec /qn /i "$env:TEMP\netdata-x64.msi" TOKEN="$TOKEN" ROOMS="$ROOMS"
174
+```
175
+
176
+</details>
177
+
178
+## Understanding the REINSTALL=ALL Parameter
179
+
180
+The `REINSTALL=ALL` parameter is a Windows Installer (MSI) standard option that forces reinstallation of all Netdata components, ensuring a clean upgrade path.
181
+
182
+**When to use REINSTALL=ALL:**
183
+
184
+- **Switching channels** (Stable ↔ Nightly) - Recommended
185
+- **Troubleshooting broken installation** - Essential
186
+- **Upgrading within the same channel** - Optional
187
+
188
+**When not to use REINSTALL = ALL:**
189
+
190
+- Fresh installations (no existing Netdata)
191
+- When you want minimal disruption (standard MSI upgrade is sufficient)
192
+
193
+:::warning
194
+
195
+The `REINSTALL = ALL` parameter ensures complete replacement of binaries but is not required for normal channel switches. The MSI installer handles upgrades automatically.
196
+
197
+:::
198
+
199
+## Verification: Confirm Your Channel
200
+
201
+After switching channels, verify which version you're running:
202
+
203
+<details>
204
+<summary>Check via Netdata Dashboard</summary>
205
+
206
+1. Open your browser to `http: //localhost:19999`
207
+2. Click the **Netdata logo** in the top-left corner
208
+3. Look for the version number:
209
+
210
+- **Stable**: `v2.1.0` (clean version number)
211
+- **Nightly**: `v2.1.0-123-nightly` (includes commit hash)
212
+
213
+</details>
214
+
215
+<br/>
216
+
217
+<details>
218
+<summary>Check via PowerShell</summary>
219
+
220
+```powershell
221
+# Get installed Netdata version
222
+Get-ItemProperty "HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*" |
223
+ Where-Object {
224
+ $_.DisplayName -like "*Netdata*"
225
+ } |
226
+ Select-Object DisplayName, DisplayVersion, Publisher
227
+```
228
+
229
+**Example output:**
230
+
231
+```
232
+DisplayName : Netdata
233
+DisplayVersion : 2.1.0
234
+Publisher : Netdata Inc.
235
+```
236
+
237
+</details>
238
+
239
+<br/>
240
+
241
+<details>
242
+<summary>Check Netdata Service Status</summary>
243
+
244
+You can also verify the Netdata service is running through the Windows Services manager:
245
+
246
+
247
+
248
+Or check via PowerShell:
249
+
250
+```powershell
251
+# Check Netdata service status
252
+Get-Service netdata | Select-Object Name, Status, DisplayName
253
+
254
+# Check service executable path
255
+Get-WmiObject win32_service | Where-Object { $_.Name -eq 'netdata' } | Select-Object PathName
256
+```
257
+
258
+</details>
259
+
260
+## Troubleshooting Common Issues
261
+
262
+<details>
263
+<summary>Issue: "Another version is already installed"</summary>
264
+
265
+**Symptoms**: MSI installer shows error about existing installation
266
+
267
+**Solution 1**: Use the `REINSTALL=ALL` parameter explicitly:
268
+
269
+```powershell
270
+msiexec /qn /i netdata-x64.msi REINSTALL=ALL
271
+```
272
+
273
+**Solution 2**: Uninstall first via Windows Add/Remove Programs, then reinstall:
274
+
275
+
276
+
277
+Or uninstall via PowerShell:
278
+
279
+```powershell
280
+# Uninstall existing installation
281
+msiexec /qn /x netdata-x64.msi
282
+
283
+# Wait for uninstall to complete
284
+Start-Sleep -Seconds 10
285
+
286
+# Reinstall with new channel
287
+msiexec /qn /i netdata-x64.msi TOKEN="<YOUR_TOKEN>" ROOMS="<YOUR_ROOMS>"
288
+```
289
+
290
+</details>
291
+
292
+<br/>
293
+
294
+<details>
295
+<summary>Issue: Cloud Connection Lost After Switch</summary>
296
+
297
+**Symptoms**: After switching channels, node doesn't appear in Netdata Cloud
298
+
299
+**Solution**: Reclaim the node:
300
+
301
+```powershell
302
+# Stop Netdata service
303
+Stop-Service netdata
304
+
305
+# Remove old cloud configuration
306
+Remove-Item "C:\Program Files\Netdata\var\lib\netdata\cloud.d\*" -Force
307
+
308
+# Reinstall with claim token
309
+msiexec /qn /i netdata-x64.msi TOKEN="<YOUR_TOKEN>" ROOMS="<YOUR_ROOMS>" REINSTALL=ALL
310
+
311
+# Start service
312
+Start-Service netdata
313
+```
314
+
315
+You can also verify the service status in Windows Services:
316
+
317
+
318
+
319
+</details>
320
+
321
+<br/>
322
+
323
+<details>
324
+<summary>Issue: Service Won't Start After Switch</summary>
325
+
326
+**Symptoms**: Netdata service fails to start after channel switch
327
+
328
+**Solution**: Check service status and perform clean reinstall:
329
+
330
+```powershell
331
+# Check service status
332
+Get-Service netdata
333
+
334
+# Check Windows Event Log for errors
335
+Get-EventLog -LogName Application -Source Netdata -Newest 20
336
+
337
+# Perform clean reinstall
338
+msiexec /qn /x netdata-x64.msi
339
+Remove-Item "C:\Program Files\Netdata" -Recurse -Force -ErrorAction SilentlyContinue
340
+Remove-Item "$env:PROGRAMDATA\Netdata" -Recurse -Force -ErrorAction SilentlyContinue
341
+msiexec /qn /i netdata-x64.msi TOKEN="<YOUR_TOKEN>" ROOMS="<YOUR_ROOMS>"
342
+```
343
+
344
+If the service still won't start, check the Windows Services manager to ensure the Netdata service is present and configured correctly:
345
+
346
+
347
+
348
+</details>
349
+
350
+## Alternative: Using Windows Add/Remove Programs
351
+
352
+For users who prefer the traditional Windows approach, you can also manage Netdata installations through the Windows Control Panel:
353
+
354
+1. **Access Add/Remove Programs:**
355
+ - Open Windows Settings → Apps & features
356
+ - Or search for "Add or remove programs" in the Start menu
357
+
358
+2. **Locate Netdata:**
359
+ - Find "Netdata" in the installed programs list
360
+ - Note the current version number
361
+
362
+ 
363
+
364
+3. **Uninstall if needed:**
365
+ - Click "Uninstall" to remove the current installation
366
+ - Then install the new channel using the MSI installer
367
+
368
+This method provides a familiar Windows experience but requires manual download and installation of the new channel.