diff options
author | Joel Hans <joel@netdata.cloud> | 2020-03-20 08:36:11 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-03-20 08:36:11 -0700 |
commit | 43f410945582104d1d2c81796f3be4da413a56ff (patch) | |
tree | 40492a494eea889a8dba90e7f55c7a52ad94adc0 /packaging | |
parent | 9e8997d6615bdc566c5f04e739d01fa3772ed256 (diff) |
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
Diffstat (limited to 'packaging')
-rw-r--r-- | packaging/installer/UPDATE.md | 165 |
1 files changed, 124 insertions, 41 deletions
diff --git a/packaging/installer/UPDATE.md b/packaging/installer/UPDATE.md index 4169ad1a01..c5f56275f9 100644 --- a/packaging/installer/UPDATE.md +++ b/packaging/installer/UPDATE.md @@ -1,74 +1,157 @@ <!-- --- title: "Update Netdata" +description: "We actively develop Netdata to add new features and remove bugs. Here's how to stay up-to-date with the +latest nightly or major releases." +date: 2020-03-12 custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/UPDATE.md --- --> # Update Netdata -![image8](https://cloud.githubusercontent.com/assets/2662304/14253735/536f4580-fa95-11e5-9f7b-99112b31a5d7.gif) +We actively develop Netdata to add new features and remove bugs, and encourage all users to ensure they're using the +most up-to-date version, whether that's nightly or major releases. -We suggest to keep your Netdata updated. We are actively developing it and you should always update to the latest -version. +Before you update Netdata using one of the methods below, check to see if your Netdata agent is already up-to-date by +opening the update modal in the dashboard. Click the **Update** button in the top navigation to open it. The modal tells +you whether your agent is up-to-date or not. -The update procedure depends on how you installed it: +![Opening the update +modal](https://user-images.githubusercontent.com/1153921/76559153-d5cced00-645b-11ea-8dcd-893f8d16f7a8.gif) -## You downloaded it from github using git +If your agent can be updated, use one of the methods below. **The method you chose for updating Netdata depends on how +you installed it.** Choose from the following list to see the appropriate update instructions for your system. -### Manual update to get the latest git commit +- [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) -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. +## One-line installer script (`kickstart.sh`) -```sh -# go to the git downloaded directory -cd /path/to/git/downloaded/netdata +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. -# update your local copy -git pull +This script downloads the latest Netdata source (either the nightly or stable version), compiles Netdata, and updates it +via reinstallation. -# run the Netdata installer -sudo ./netdata-installer.sh +```bash +bash <(curl -Ss https://my-netdata.io/kickstart.sh) +``` + +> ⚠️ 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. See the [`kickstart.sh` +> documentation](methods/kickstart.md#optional-parameters-to-alter-your-installation) for more information on these +> parameters and what they do. + +## `.deb` or `.rpm` packages + +If you installed Netdata with `.deb` or `.rpm` packages, use your distribution's package manager 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 Netdata, and restarts it. + +```bash +apt-get install netdata # Ubuntu/Debian +dnf install netdata # Fedora/RHEL +yum install netdata # CentOS +zypper in netdata # openSUSE ``` -Netdata will be restarted with the new version. 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. +> You may need to escalate privileges using `sudo`. -### Manual update to get the latest nightly build +## Pre-built static binary for 64-bit systems (`kickstart-static64.sh`) -The `kickstart.sh` and `kickstart-static64.sh` one-liners will do a one-time update to the latest nightly build, if -executed as follows: +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. -```sh -# kickstart.sh -bash <(curl -Ss https://my-netdata.io/kickstart.sh) --no-updates +This script downloads the latest Netdata source (either the nightly or stable version), compiles Netdata, and updates it +via reinstallation. -# kickstart-static64.sh -bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) --no-updates +```bash +bash <(curl -Ss https://my-netdata.io/kickstart-static64.sh) ``` -### Auto-update +> ⚠️ 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. See the [`kickstart-static64.sh` +> documentation](methods/kickstart-64.md#optional-parameters-to-alter-your-installation) for more information on these +> parameters and what they do. -_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._ +## Docker -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. +Docker-based installations do not update automatically. To update an 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. -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. +First, pull the latest version of the image. -## You downloaded a binary package +```bash +docker pull netdata/netdata:latest +``` + +Next, to stop and remove any containers using the `netdata/netdata` image. Replace `netdata` if you changed +it from the default in our [Docker installation instructions](../docker/README.md#run-netdata-with-the-docker-command). + +```bash +docker stop netdata +docker rm netdata +``` + +You can now re-create your Netdata container using the `docker` command or a `docker-compose.yml` file. See our [Docker +installation instructions](../docker/README.md#run-netdata-with-the-docker-command) for details. For example, using the +`docker` command: + +```bash +docker run -d --name=netdata \ + -p 19999:19999 \ + -v /etc/passwd:/host/etc/passwd:ro \ + -v /etc/group:/host/etc/group:ro \ + -v /proc:/host/proc:ro \ + -v /sys:/host/sys:ro \ + -v /etc/os-release:/host/etc/os-release:ro \ + --cap-add SYS_PTRACE \ + --security-opt apparmor=unconfined \ + netdata/netdata +``` -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. +## macOS + +If you installed Netdata on your macOS system using Homebrew, you can explictly request an update: + +```bash +brew upgrade netdata +``` + +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. + +## Manual installation from Git + +If you installed Netdata manually from Git using `netdata-installer.sh`, 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) +``` + +Then, 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)](<>) |