@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 368 lines 11.9 KB
Rendered Raw
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 ![Windows Installer GUI](https://raw.githubusercontent.com/netdata/docs-images/refs/heads/master/windows/release/windows-installer-gui.png)
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 ![Windows Installer GUI](https://raw.githubusercontent.com/netdata/docs-images/refs/heads/master/windows/release/windows-installer-gui.png)
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 ![Windows Services - Netdata](https://raw.githubusercontent.com/netdata/docs-images/refs/heads/master/windows/release/windows-services-netdata.png)
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 ![Windows Add/Remove Programs](https://raw.githubusercontent.com/netdata/docs-images/refs/heads/master/windows/release/windows-add-remove-programs.png)
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 ![Windows Services - Netdata](https://raw.githubusercontent.com/netdata/docs-images/refs/heads/master/windows/release/windows-services-netdata.png)
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 ![Windows Services - Netdata](https://raw.githubusercontent.com/netdata/docs-images/refs/heads/master/windows/release/windows-services-netdata.png)
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 ![Windows Add/Remove Programs](https://raw.githubusercontent.com/netdata/docs-images/refs/heads/master/windows/release/windows-add-remove-programs.png)
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.