Update the update instructions with per-method details (#8394)
* Init new version of update doc * Update the gif to show an out-of-date agent * Tweaks * No more future
Joel Hans committed
Mar 20, 2020 at 08:36 UTC
43f410945582104d1d2c81796f3be4da413a56ff
1 file changed
+124
-41
packaging/installer/UPDATE.md
+124
-41
@@ -1,74 +1,157 @@
1
<!--
2
---
3
title: "Update Netdata"
4
+description: "We actively develop Netdata to add new features and remove bugs. Here's how to stay up-to-date with the
5
+latest nightly or major releases."
6
+date: 2020-03-12
7
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UPDATE.md
8
---
9
-->
10
11
# Update Netdata
12
10
-
13
+We actively develop Netdata to add new features and remove bugs, and encourage all users to ensure they're using the
14
+most up-to-date version, whether that's nightly or major releases.
15
12
-We suggest to keep your Netdata updated. We are actively developing it and you should always update to the latest
13
-version.
16
+Before you update Netdata using one of the methods below, check to see if your Netdata agent is already up-to-date by
17
+opening the update modal in the dashboard. Click the **Update** button in the top navigation to open it. The modal tells
18
+you whether your agent is up-to-date or not.
19
15
-The update procedure depends on how you installed it:
20
+
22
17
-## You downloaded it from github using git
23
+If your agent can be updated, use one of the methods below. **The method you chose for updating Netdata depends on how
24
+you installed it.** Choose from the following list to see the appropriate update instructions for your system.
25
19
-### Manual update to get the latest git commit
26
+- [One-line installer script (`kickstart.sh`)](#one-line-installer-script-kickstartsh)
27
+- [`.deb` or `.rpm` packages](#deb-or-rpm-packages)
28
+- [Pre-built static binary for 64-bit systems
29
+ (`kickstart-static64.sh`)](#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh)
30
+- [Docker](#docker)
31
+- [macOS](#macos)
32
+- [Manual installation from Git](#manual-installation-from-git)
33
21
-Netdata versions older than `v1.12.0-rc2-52` had a `netdata-updater.sh` script in the root directory of the source code,
22
-which has now been deprecated. The manual process that works for all versions to get the latest commit in git is to use
23
-the `netdata-installer.sh`. The installer preserves your custom configuration and updates the information of the
24
-installation in the `.environment` file under the user configuration directory.
34
+## One-line installer script (`kickstart.sh`)
35
26
-```sh
27
-# go to the git downloaded directory
28
-cd /path/to/git/downloaded/netdata
36
+If you installed Netdata using our one-line automatic installation script, run it again to update Netdata. Any custom
37
+settings present in your Netdata configuration directory (typically at `/etc/netdata`) persists during this process.
38
30
-# update your local copy
31
-git pull
39
+This script downloads the latest Netdata source (either the nightly or stable version), compiles Netdata, and updates it
40
+via reinstallation.
41
33
-# run the Netdata installer
34
-sudo ./netdata-installer.sh
42
+```bash
43
+bash <(curl -Ss https://my-netdata.io/kickstart.sh)
44
+```
45
+
46
+> ⚠️ If you installed Netdata with any optional parameters, such as `--no-updates` to disable automatic updates, and
47
+> want to retain those settings, you need to set them again during this process. See the [`kickstart.sh`
48
+> documentation](methods/kickstart.md#optional-parameters-to-alter-your-installation) for more information on these
49
+> parameters and what they do.
50
+
51
+## `.deb` or `.rpm` packages
52
+
53
+If you installed Netdata with `.deb` or `.rpm` packages, use your distribution's package manager update Netdata. Any
54
+custom settings present in your Netdata configuration directory (typically at `/etc/netdata`) persists during this
55
+process.
56
+
57
+Your package manager grabs a new package from our hosted repository, updates Netdata, and restarts it.
58
+
59
+```bash
60
+apt-get install netdata # Ubuntu/Debian
61
+dnf install netdata # Fedora/RHEL
62
+yum install netdata # CentOS
63
+zypper in netdata # openSUSE
64
```
65
37
-Netdata will be restarted with the new version. Keep in mind, Netdata may now have new features, or certain old features
38
-may now behave differently. So pay some attention to it after updating.
66
+> You may need to escalate privileges using `sudo`.
67
40
-### Manual update to get the latest nightly build
68
+## Pre-built static binary for 64-bit systems (`kickstart-static64.sh`)
69
42
-The `kickstart.sh` and `kickstart-static64.sh` one-liners will do a one-time update to the latest nightly build, if
43
-executed as follows:
70
+If you installed Netdata using the pre-built static binary, run the `kickstart-static64.sh` script again to update
71
+Netdata. Any custom settings present in your Netdata configuration directory (typically at `/etc/netdata`) persists
72
+during this process.
73
45
-```sh
46
-# kickstart.sh
47
-bash <(curl -Ss https://my-netdata.io/kickstart.sh) --no-updates
74
+This script downloads the latest Netdata source (either the nightly or stable version), compiles Netdata, and updates it
75
+via reinstallation.
76
49
-# kickstart-static64.sh
50
-bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --no-updates
77
+```bash
78
+bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh)
79
```
80
53
-### Auto-update
81
+> ⚠️ If you installed Netdata with any optional parameters, such as `--no-updates` to disable automatic updates, and
82
+> want to retain those settings, you need to set them again during this process. See the [`kickstart-static64.sh`
83
+> documentation](methods/kickstart-64.md#optional-parameters-to-alter-your-installation) for more information on these
84
+> parameters and what they do.
85
55
-_Please, consider the risks of running an auto-update. Something can always go wrong. Keep an eye on your installation,
56
-and run a manual update if something ever fails._
86
+## Docker
87
58
-Calling the `netdata-installer.sh` with the `--auto-update` or `-u` option will create the `netdata-updater` script
59
-under either `/etc/cron.daily/`, or `/etc/periodic/daily/`. Whenever the `netdata-updater` is executed, it checks if a
60
-newer nightly build is available and then handles the download, installation and Netdata restart.
88
+Docker-based installations do not update automatically. To update an agent running in a Docker container, you must pull
89
+the [latest image from Docker hub](https://hub.docker.com/r/netdata/netdata), stop and remove the container, and
90
+re-create it using the latest image.
91
62
-Note that after Jan 2019, the `kickstart.sh` one-liner `bash <(curl -Ss https://my-netdata.io/kickstart.sh)` calls the
63
-`netdata-installer.sh` with the auto-update option. So if you just run the one-liner without options once, your Netdata
64
-will be kept auto-updated.
92
+First, pull the latest version of the image.
93
66
-## You downloaded a binary package
94
+```bash
95
+docker pull netdata/netdata:latest
96
+```
97
+
98
+Next, to stop and remove any containers using the `netdata/netdata` image. Replace `netdata` if you changed
99
+it from the default in our [Docker installation instructions](../docker/README.md#run-netdata-with-the-docker-command).
100
+
101
+```bash
102
+docker stop netdata
103
+docker rm netdata
104
+```
105
+
106
+You can now re-create your Netdata container using the `docker` command or a `docker-compose.yml` file. See our [Docker
107
+installation instructions](../docker/README.md#run-netdata-with-the-docker-command) for details. For example, using the
108
+`docker` command:
109
+
110
+```bash
111
+docker run -d --name=netdata \
112
+ -p 19999:19999 \
113
+ -v /etc/passwd:/host/etc/passwd:ro \
114
+ -v /etc/group:/host/etc/group:ro \
115
+ -v /proc:/host/proc:ro \
116
+ -v /sys:/host/sys:ro \
117
+ -v /etc/os-release:/host/etc/os-release:ro \
118
+ --cap-add SYS_PTRACE \
119
+ --security-opt apparmor=unconfined \
120
+ netdata/netdata
121
+```
122
68
-If you installed it from a binary package, the best way is to **obtain a newer copy** from the source you got it in the
69
-first place.
123
+## macOS
124
+
125
+If you installed Netdata on your macOS system using Homebrew, you can explictly request an update:
126
+
127
+```bash
128
+brew upgrade netdata
129
+```
130
+
131
+Homebrew downloads the latest Netdata via the
132
+[formulae](https://github.com/Homebrew/homebrew-core/blob/master/Formula/netdata.rb), ensures all dependencies are met,
133
+and updates Netdata via reinstallation.
134
+
135
+## Manual installation from Git
136
+
137
+If you installed Netdata manually from Git using `netdata-installer.sh`, you can run that installer again to update your
138
+agent. First, run our automatic requirements installer, which works on many Linux distributions, to ensure your system
139
+has the dependencies necessary for new features.
140
+
141
+```bash
142
+bash <(curl -sSL https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh)
143
+```
144
+
145
+Then, navigate to the directory where you first cloned the Netdata repository, pull the latest source code, and run
146
+`netdata-install.sh` again. This process compiles Netdata with the latest source code and updates it via reinstallation.
147
+
148
+```bash
149
+cd /path/to/netdata/git
150
+git pull origin master
151
+sudo ./netdata-installer.sh
152
+```
153
71
-If a newer version of Netdata is not available from the source you got it, we suggest to uninstall the version you have
72
-and follow the [installation](README.md) instructions for installing a fresh version of Netdata.
154
+> ⚠️ If you installed Netdata with any optional parameters, such as `--no-updates` to disable automatic updates, and
155
+> want to retain those settings, you need to set them again during this process.
156
157
[](<>)