Adding upstream version 1.29.0.upstream/1.29.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 127 insertions, 31 deletions

diff --git a/packaging/installer/UPDATE.md b/packaging/installer/UPDATE.md
index ab5b558f7..ba57c8cc5 100644
--- a/packaging/installer/UPDATE.md
+++ b/packaging/installer/UPDATE.md
@@ -1,57 +1,153 @@
-# Updating Netdata after its installation
+<!--
+title: "Update the Netdata Agent"
+description: "If you opted out of automatic updates, you need to update your Netdata Agent to the latest nightly or stable version."
+custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UPDATE.md
+-->
 
-![image8](https://cloud.githubusercontent.com/assets/2662304/14253735/536f4580-fa95-11e5-9f7b-99112b31a5d7.gif)
+# Update the Netdata Agent
 
-We suggest to keep your Netdata updated. We are actively developing it and you should always update to the latest version.
+By default, the Netdata Agent automatically updates with the latest nightly version. If you opted out of automatic
+updates, you need to update your Netdata Agent to the latest nightly or stable version.
 
-The update procedure depends on how you installed it:
+> 💡 Looking to reinstall the Netdata Agent to enable a feature, update an Agent that cannot update automatically, or
+> troubleshoot an error during the installation process? See our [reinstallation doc](/packaging/installer/REINSTALL.md)
+> for reinstallation steps.
 
-## You downloaded it from github using git
+Before you update the Netdata Agent, check to see if your Netdata Agent is already up-to-date by clicking on the update
+icon in the local Agent dashboard's top navigation. This modal informs you whether your Agent needs an update or not.
 
-### Manual update to get the latest git commit
+![Opening the Agent's Update modal](https://user-images.githubusercontent.com/1153921/99738428-add06780-2a87-11eb-8268-0e17b689eb3f.gif)
 
-Netdata versions older than `v1.12.0-rc2-52` had a `netdata-updater.sh` script in the root directory of the source code, which has now been deprecated. The manual process that works for all versions to get the latest commit in git is to use the `netdata-installer.sh`. The installer preserves your custom configuration and updates the information of the installation in the `.environment` file under the user configuration directory.
+## Determine which installation method you used
 
-```sh
-# go to the git downloaded directory
-cd /path/to/git/downloaded/netdata
+If you are not sure where your Netdata config directory is, see the [configuration doc](/docs/configure/nodes.md). In
+most installations, this is `/etc/netdata`.
 
-# update your local copy
-git pull
+Use `cd` to navigate to the Netdata config directory, then use `ls -a` to look for a file called `.environment`.
 
-# run the Netdata installer
-sudo ./netdata-installer.sh
+-   If the `.environment` file _does not_ exist, reinstall with your [package manager](#deb-or-rpm-packages).
+-   If the `.environment` file _does_ exist, check its contents with `less .environment`.
+    -   If `IS_NETDATA_STATIC_BINARY` is `"yes"`, update using the [pre-built static
+        binary](#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh).
+    -   In all other cases, update using the [one-line installer script](#one-line-installer-script-kickstartsh).
+
+Next, use the appropriate method to update the Netdata Agent:
+
+-   [One-line installer script (`kickstart.sh`)](#one-line-installer-script-kickstartsh)
+-   [`.deb` or `.rpm` packages](#deb-or-rpm-packages)
+-   [Pre-built static binary for 64-bit systems (`kickstart-static64.sh`)](#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh)
+-   [Docker](#docker)
+-   [macOS](#macos)
+-   [Manual installation from Git](#manual-installation-from-git)
+
+## One-line installer script (`kickstart.sh`)
+
+If you installed Netdata using our one-line automatic installation script, run it again to update Netdata. Any custom
+settings present in your Netdata configuration directory (typically at `/etc/netdata`) persists during this process.
+
+This script will automatically run the update script that was installed as part of the initial install (even if
+you disabled automatic updates) and preserve the existing install options you specified.
+
+If you installed Netdata using an installation prefix, you will need to add an `--install` option specifying
+that prefix to this command to make sure it finds Netdata.
+
+```bash
+bash <(curl -Ss https://my-netdata.io/kickstart.sh)
+```
+
+> ❗ If the above command fails, you can [reinstall
+> Netdata](/packaging/installer/REINSTALL.md#one-line-installer-script-kickstartsh) to get the latest version. This also
+> preserves your [configuration](/docs/configure/nodes.md) in `netdata.conf` or other files.
+
+## `.deb` or `.rpm` packages
+
+If you installed Netdata with [`.deb` or `.rpm` packages](/packaging/installer/methods/packages.md), use your
+distribution's package manager to update Netdata. Any custom settings present in your Netdata configuration directory
+(typically at `/etc/netdata`) persists during this process.
+
+Your package manager grabs a new package from our hosted repository, updates the Netdata Agent, and restarts it.
+
+```bash
+apt-get install netdata     # Ubuntu/Debian
+dnf install netdata         # Fedora/RHEL
+yum install netdata         # CentOS
+zypper in netdata           # openSUSE
+```
+
+> You may need to escalate privileges using `sudo`.
+
+## Pre-built static binary for 64-bit systems (`kickstart-static64.sh`)
+
+If you installed Netdata using the pre-built static binary, run the `kickstart-static64.sh` script again to update
+Netdata. Any custom settings present in your Netdata configuration directory (typically at `/etc/netdata`) persists
+during this process.
+
+This script will automatically run the update script that was installed as part of the initial install (even if
+you disabled automatic updates) and preserve the existing install options you specified.
+
+```bash
+bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh)
 ```
 
-_Netdata will be restarted with the new version._
+> ❗ If the above command fails, you can [reinstall
+> Netdata](/packaging/installer/REINSTALL.md#pre-built-static-binary-for-64-bit-systems-kickstart-static64sh) to get the
+> latest version. This also preserves your [configuration](/docs/configure/nodes.md) in `netdata.conf` or other files.
+
+## Docker
 
-Keep in mind, Netdata may now have new features, or certain old features may now behave differently. So pay some attention to it after updating.
+Docker-based installations do not update automatically. To update an Netdata Agent running in a Docker container, you
+must pull the [latest image from Docker Hub](https://hub.docker.com/r/netdata/netdata), stop and remove the container,
+and re-create it using the latest image.
 
-### Manual update to get the latest nightly build
+First, pull the latest version of the image.
 
-The `kickstart.sh` and `kickstart-static64.sh` one-liners will do a one-time update to the latest nightly build, if executed as follows:
+```bash
+docker pull netdata/netdata:latest
+```
 
-```sh
-# kickstart.sh
-bash <(curl -Ss https://my-netdata.io/kickstart.sh) --no-updates
+Next, to stop and remove any containers using the `netdata/netdata` image. Replace `netdata` if you changed it from the
+default.
 
-# kickstart-static64.sh
-bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --no-updates
+```bash
+docker stop netdata
+docker rm netdata
 ```
 
-### Auto-update
+You can now re-create your Netdata container using the `docker` command or a `docker-compose.yml` file. See our [Docker
+installation instructions](/packaging/docker/README.md#create-a-new-netdata-agent-container) for details.
 
-_Please, consider the risks of running an auto-update. Something can always go wrong. Keep an eye on your installation, and run a manual update if something ever fails._
+## macOS
 
-Calling the `netdata-installer.sh` with the `--auto-update` or `-u` option will create the `netdata-updater` script under 
-either  `/etc/cron.daily/`, or `/etc/periodic/daily/`. Whenever the `netdata-updater` is executed, it checks if a newer nightly build is available and then handles the download, installation and Netdata restart.  
+If you installed Netdata on your macOS system using Homebrew, you can explicitly request an update:
 
-Note that after Jan 2019, the `kickstart.sh` one-liner `bash <(curl -Ss https://my-netdata.io/kickstart.sh)` calls the `netdata-installer.sh` with the auto-update option. So if you just run the one-liner without options once, your Netdata will be kept auto-updated.
+```bash
+brew upgrade netdata
+```
 
-## You downloaded a binary package
+Homebrew downloads the latest Netdata via the
+[formulae](https://github.com/Homebrew/homebrew-core/blob/master/Formula/netdata.rb), ensures all dependencies are met,
+and updates Netdata via reinstallation.
 
-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 first place.
+## Manual installation from Git
+
+If you installed [Netdata manually from Git](/packaging/installer/methods/manual.md), you can run that installer again
+to update your agent. First, run our automatic requirements installer, which works on many Linux distributions, to
+ensure your system has the dependencies necessary for new features.
+
+```bash
+bash <(curl -sSL https://raw.githubusercontent.com/netdata/netdata/master/packaging/installer/install-required-packages.sh)
+```
+
+Navigate to the directory where you first cloned the Netdata repository, pull the latest source code, and run
+`netdata-install.sh` again. This process compiles Netdata with the latest source code and updates it via reinstallation.
+
+```bash
+cd /path/to/netdata/git
+git pull origin master
+sudo ./netdata-installer.sh
+```
 
-If a newer version of Netdata is not available from the source you got it, we suggest to uninstall the version you have and follow the [installation](README.md) instructions for installing a fresh version of Netdata.
+> ⚠️ If you installed Netdata with any optional parameters, such as `--no-updates` to disable automatic updates, and
+> want to retain those settings, you need to set them again during this process.
 
 [![analytics](https://www.google-analytics.com/collect?v=1&aip=1&t=pageview&_s=1&ds=github&dr=https%3A%2F%2Fgithub.com%2Fnetdata%2Fnetdata&dl=https%3A%2F%2Fmy-netdata.io%2Fgithub%2Finstaller%2FUPDATE&_u=MAC~&cid=5792dfd7-8dc4-476b-af31-da2fdb9f93d2&tid=UA-64295674-3)](<>)