Switch install types (#20564)
Co-authored-by: Ilya Mashchenko <ilya@netdata.cloud>
Kanela committed
Jun 24, 2025 at 23:39 UTC
67960c326b42daa70d2ef57c3a5898f3ac4da66a
1 file changed
+267
docs/learn/switching-install-types.md
new
+267
@@ -0,0 +1,267 @@
1
+# Switching Netdata Install Types and Release Channels
2
+
3
+You can switch between different Netdata installation types and release channels based on your needs. This guide covers both scenarios with step-by-step instructions.
4
+
5
+## Switching Install Types
6
+
7
+### Data Backups When Switching Install Types
8
+
9
+Before switching install types, you need to back up your configuration and data to preserve your settings.
10
+
11
+<details>
12
+<summary><strong>For Native Packages and Local Builds</strong></summary><br/>
13
+
14
+When backing up configuration and data for install types other than static builds or Docker containers, you should back up these directories:
15
+
16
+- `/etc/netdata` (excluding `/etc/netdata/.environment` and `/etc/netdata/.install-type`)
17
+- `/var/cache/netdata`
18
+- `/var/lib/netdata`
19
+
20
+:::warning
21
+
22
+You must exclude the `.environment` and `.install-type` files from your backup. Copying these files from one install type to another will break updates.
23
+
24
+:::
25
+
26
+</details>
27
+
28
+<br/>
29
+
30
+<details>
31
+<summary><strong>For Docker Containers</strong></summary><br/>
32
+
33
+When backing up configuration and data for Docker containers, you should back up these paths from inside the container:
34
+
35
+- `/etc/netdata` (excluding `/etc/netdata/.environment` and `/etc/netdata/.install-type`)
36
+- `/var/cache/netdata`
37
+- `/var/lib/netdata`
38
+
39
+:::warning
40
+
41
+You must exclude the `.environment` and `.install-type` files from your backup. Copying these files from one install type to another will break updates.
42
+
43
+:::
44
+
45
+</details>
46
+
47
+<br/>
48
+
49
+<details>
50
+<summary><strong>For Static Builds</strong></summary><br/>
51
+
52
+When backing up configuration and data for static builds, you should back up these directories:
53
+
54
+- `/opt/netdata/etc/netdata` (excluding `/opt/netdata/etc/netdata/.environment` and `/opt/netdata/etc/netdata/.install-type`)
55
+- `/opt/netdata/var/cache/netdata`
56
+- `/opt/netdata/var/lib/netdata`
57
+
58
+:::warning
59
+
60
+You must exclude the `.environment` and `.install-type` files from your backup. Copying these files from one install type to another will break updates.
61
+
62
+:::
63
+
64
+</details>
65
+
66
+<br/>
67
+
68
+<details>
69
+<summary><strong>Switching Between Install Types (Non-Docker)</strong></summary><br/>
70
+
71
+For all install types other than Docker images, you can use this officially supported method:
72
+
73
+1. **Back up your configuration and data** that you want to preserve using the appropriate method above.
74
+
75
+2. **Run the kickstart script with clean reinstall:**
76
+
77
+ ```bash
78
+ wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh
79
+ sh /tmp/netdata-kickstart.sh --reinstall-clean [OPTIONS_FOR_DESIRED_INSTALL_TYPE]
80
+ ```
81
+
82
+3. **Restore your backups** to the appropriate paths in the new installation.
83
+
84
+</details>
85
+
86
+<br/>
87
+
88
+<details>
89
+<summary><strong>Switching From Native/Static/Local to Docker</strong></summary><br/>
90
+
91
+To switch from a native, static, or local install to a Docker image:
92
+
93
+1. **Back up your configuration and data** that you want to preserve.
94
+
95
+2. **Uninstall the existing installation:**
96
+
97
+ ```bash
98
+ wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh
99
+ sh /tmp/netdata-kickstart.sh --uninstall
100
+ ```
101
+
102
+3. **Start the Docker container** for the Netdata agent.
103
+
104
+4. **Restore your backup contents** to the respective paths inside the Docker container (the paths within the container are the same as those used for a native package install on the host).
105
+
106
+5. **Restart the Docker container** to apply the restored configuration.
107
+
108
+</details>
109
+
110
+<br/>
111
+
112
+<details>
113
+<summary><strong>Switching From Docker to Native/Static/Local</strong></summary><br/>
114
+
115
+To switch from a Docker container to a different install type:
116
+
117
+1. **Back up your configuration and data** that you want to preserve from inside the container.
118
+
119
+2. **Remove the container.**
120
+
121
+3. **Install Netdata using the kickstart script:**
122
+
123
+ ```bash
124
+ wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh
125
+ sh /tmp/netdata-kickstart.sh [OPTIONS_FOR_DESIRED_INSTALL_TYPE]
126
+ ```
127
+
128
+4. **Restore your backups** to the appropriate paths in the new installation.
129
+
130
+</details>
131
+
132
+## Switching Between Release Channels
133
+
134
+### Static Builds and Local Builds
135
+
136
+For static builds and local builds, you can simply run the kickstart script with the reinstall option:
137
+
138
+<details>
139
+<summary><strong>Switch to Stable Channel</strong></summary><br/>
140
+
141
+```bash
142
+wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh
143
+sh /tmp/netdata-kickstart.sh --reinstall --stable-channel
144
+```
145
+
146
+</details>
147
+
148
+<br/>
149
+
150
+<details>
151
+<summary><strong>Switch to Nightly Channel</strong></summary><br/>
152
+
153
+```bash
154
+wget -O /tmp/netdata-kickstart.sh https://get.netdata.cloud/kickstart.sh
155
+sh /tmp/netdata-kickstart.sh --reinstall --nightly-channel
156
+```
157
+
158
+</details>
159
+
160
+### Docker Containers
161
+
162
+Follow the standard container recreation process used for updates, but replace the image tag with the one corresponding to your target release channel:
163
+
164
+- **Stable**: Use the `stable` tag
165
+- **Nightly**: Use the `latest` tag
166
+
167
+### Native Packages
168
+
169
+#### Debian/Ubuntu
170
+
171
+<details>
172
+<summary><strong>Switch from Nightly to Stable</strong></summary><br/>
173
+
174
+```bash
175
+# Install stable repository (automatically removes nightly repo)
176
+sudo apt install netdata-repo
177
+sudo apt update
178
+sudo apt remove netdata
179
+sudo apt install netdata
180
+```
181
+
182
+</details>
183
+
184
+<br/>
185
+
186
+<details>
187
+<summary><strong>Switch from Stable to Nightly</strong></summary><br/>
188
+
189
+```bash
190
+# Install nightly repository (automatically removes stable repo)
191
+sudo apt install netdata-repo-edge
192
+sudo apt update
193
+sudo apt remove netdata
194
+sudo apt install netdata
195
+```
196
+
197
+</details>
198
+
199
+<br/>
200
+
201
+#### Fedora/RHEL
202
+
203
+<details>
204
+<summary><strong>Switch from Nightly to Stable</strong></summary><br/>
205
+
206
+```bash
207
+# Install stable repository (automatically removes nightly repo)
208
+sudo dnf install --allowerasing netdata-repo
209
+sudo dnf remove netdata
210
+sudo dnf install --refresh netdata
211
+```
212
+
213
+</details>
214
+
215
+<br/>
216
+
217
+<details>
218
+<summary><strong>Switch from Stable to Nightly</strong></summary><br/>
219
+
220
+```bash
221
+# Install nightly repository (automatically removes stable repo)
222
+sudo dnf install --allowerasing netdata-repo-edge
223
+sudo dnf remove netdata
224
+sudo dnf install --refresh netdata
225
+```
226
+
227
+</details>
228
+
229
+<br/>
230
+
231
+#### openSUSE
232
+
233
+<details>
234
+<summary><strong>Switch from Nightly to Stable</strong></summary><br/>
235
+
236
+```bash
237
+# Install stable repository (automatically removes nightly repo)
238
+sudo zypper install --allowerasing netdata-repo
239
+sudo zypper refresh
240
+sudo zypper remove netdata
241
+sudo zypper install netdata
242
+```
243
+
244
+</details>
245
+
246
+<br/>
247
+
248
+<details>
249
+<summary><strong>Switch from Stable to Nightly</strong></summary><br/>
250
+
251
+```bash
252
+# Install nightly repository (automatically removes stable repo)
253
+sudo zypper install --allowerasing netdata-repo-edge
254
+sudo zypper refresh
255
+sudo zypper remove netdata
256
+sudo zypper install netdata
257
+```
258
+
259
+</details>
260
+
261
+<br/>
262
+
263
+:::tip
264
+
265
+When switching release channels with native packages, the repository configuration packages automatically handle the removal of the previous channel's repository to prevent conflicts.
266
+
267
+:::