From e3f03ff5004cdf146262412eb87f2b70e051d1e8 Mon Sep 17 00:00:00 2001
From: Joshua Powers <powersj@fastmail.com>
Date: Tue, 7 May 2024 10:17:56 -0600
Subject: [PATCH] docs: Add install guide (#15289)

---
 docs/INSTALL_GUIDE.md | 156 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 docs/INSTALL_GUIDE.md

diff --git a/docs/INSTALL_GUIDE.md b/docs/INSTALL_GUIDE.md
new file mode 100644
index 000000000..4b121c9fd
--- /dev/null
+++ b/docs/INSTALL_GUIDE.md
@@ -0,0 +1,156 @@
+# Installation
+
+Telegraf compiles to a single static binary, which makes it easy to install.
+Both InfluxData and the community provide for a wide range of methods to install
+Telegraf from. For details on each release, view the [changelog][] for the
+latest updates and changes by version.
+
+[changelog]: /CHANGELOG.md
+
+There are many places to obtain Telegraf from:
+
+* [Binary downloads](#binary-downloads)
+* [Homebrew](#homebrew)
+* [InfluxData Linux package repository](#influxdata-linux-package-repository)
+* [Official Docker images](#official-docker-images)
+* [Helm charts](#helm-charts)
+* [Nightly builds](#nightly-builds)
+* [Build from source](#build-from-source)
+* [Custom builder](#custom-builder)
+
+## Binary downloads
+
+Binary downloads for a wide range of architectures and operating systems are
+available from the [InfluxData downloads][] page or from the
+[GitHub Releases][] page.
+
+[InfluxData downloads]: https://www.influxdata.com/downloads
+[GitHub Releases]: https://github.com/influxdata/telegraf/releases
+
+## Homebrew
+
+A [Homebrew Formula][] for Telegraf that updates after each release:
+
+```shell
+brew update
+brew install telegraf
+```
+
+Note that the Homebrew organization builds Telegraf itself and does not use
+binaries built by InfluxData. This is important as Homebrew builds with CGO,
+which means there are some differences between the official binaries and those
+found with Homebrew.
+
+[Homebrew Formula]: https://formulae.brew.sh/formula/telegraf
+
+## InfluxData Linux package repository
+
+InfluxData provides a package repo that contains both DEB and RPM packages.
+
+### DEB
+
+For DEB-based platforms (e.g. Ubuntu and Debian) run the following to add the
+repo GPG key and setup a new sources.list entry:
+
+```shell
+# influxdata-archive_compat.key GPG fingerprint:
+#     9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
+wget -q https://repos.influxdata.com/influxdata-archive_compat.key
+echo '393e8779c89ac8d958f81f942f9ad7fb82a25e133faddaf92e15b16e6ac9ce4c influxdata-archive_compat.key' | sha256sum -c && cat influxdata-archive_compat.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg > /dev/null
+echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' | sudo tee /etc/apt/sources.list.d/influxdata.list
+sudo apt-get update && sudo apt-get install telegraf
+```
+
+### RPM
+
+For RPM-based platforms (e.g. RHEL, CentOS) use the following to create a repo
+file and install telegraf:
+
+```shell
+# influxdata-archive_compat.key GPG fingerprint:
+#     9D53 9D90 D332 8DC7 D6C8 D3B9 D8FF 8E1F 7DF8 B07E
+cat <<EOF | sudo tee /etc/yum.repos.d/influxdata.repo
+[influxdata]
+name = InfluxData Repository - Stable
+baseurl = https://repos.influxdata.com/stable/\$basearch/main
+enabled = 1
+gpgcheck = 1
+gpgkey = https://repos.influxdata.com/influxdata-archive_compat.key
+EOF
+sudo yum install telegraf
+```
+
+## Official Docker images
+
+Telegraf is available as an [Official image][] on DockerHub. Official images
+are a curated set of Docker Images that also automatically get security updates
+from Docker, follow a set of best practices, and are available via a shortcut
+syntax which omits the organization.
+
+InfluxData maintains a Debian and Alpine based image across the last three
+minor releases. To pull the latest Telegraf images:
+
+```shell
+# latest Debian-based image
+docker pull telegraf
+# latest Alpine-based image
+docker pull telegraf:alpine
+```
+
+See the [Telegraf DockerHub][] page for complete details on available images,
+versions, and tags.
+
+[official image]: https://docs.docker.com/trusted-content/official-images/
+[Telegraf DockerHub]: https://hub.docker.com/_/telegraf
+
+## Helm charts
+
+A community-supported [helm chart][] is also available:
+
+```shell
+helm repo add influxdata https://helm.influxdata.com/
+helm search repo influxdata
+```
+
+[helm chart]: https://github.com/influxdata/helm-charts/tree/master/charts/telegraf
+
+## Nightly builds
+
+[Nightly builds][] are available and are generated from the master branch each
+day at around midnight UTC. The artifacts include both binary packages, RPM &
+DEB packages, as well as nightly Docker images that are hosted on [quay.io][].
+
+[Nightly builds]: /docs/NIGHTLIES.md
+[quay.io]: https://quay.io/repository/influxdb/telegraf-nightly?tab=tags&tag=latest
+
+## Build from source
+
+Telegraf generally follows the latest version of Go and requires GNU make to use
+the Makefile for builds.
+
+On Windows, the makefile requires the use of a bash terminal to support all
+makefile targets. An easy option to get bash for windows is using the version
+that comes with [git for windows](https://gitforwindows.org/).
+
+1. [Install Go](https://golang.org/doc/install)
+2. Clone the Telegraf repository:
+
+   ```shell
+   git clone https://github.com/influxdata/telegraf.git
+   ```
+
+3. Run `make build` from the source directory
+
+   ```shell
+   cd telegraf
+   make build
+   ```
+
+## Custom builder
+
+Telegraf also provides a way of building a custom minimized binary using the
+[custom builder][]. This takes a user's configuration file(s), determines what
+plugins are required, and builds a binary with only those plugins. This greatly
+reduces the size of the Telegraf binary.
+
+[custom builder]: /tools/custom_builder