Improve get started/installation docs (#10995)
* Finish initial draft * Finish with draft of installation flow * Change analytics path * Rename file and improve flow * Fix link * Improvements for Robin * Clean up title * Cleanup and feedback from Robin and Odysseas
Joel Hans committed
Apr 22, 2021 at 10:41 UTC
a494b4144ee4e8a87dcdd2e0ce9b37987c4332cc
3 files changed
+212
-218
docs/get-started.mdx
new
+172
@@ -0,0 +1,172 @@
1
+---
2
+title: "Get started with Netdata"
3
+description: "Download and install the open-source Netdata monitoring agent on physical/virtual servers, Linux (Ubuntu/Debian/CentOS/etc), Docker, Kubernetes, and many others, often with one command."
4
+type: how-to
5
+sidebar_label: "Get started"
6
+custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/get-started.mdx
7
+---
8
+
9
+import { OneLineInstall } from '../src/components/OneLineInstall/'
10
+import { Install, InstallBox } from '../src/components/Install/'
11
+
12
+# Get started with Netdata
13
+
14
+Netdata is an free and open-source (FOSS) monitoring agent that collects thousands of hardware and software metrics from
15
+any physical or virtual system (we call them _nodes_) and organizes them in an easy-to-use and -navigate interface.
16
+
17
+Together with [Netdata Cloud](https://learn.netdata.cloud/docs/cloud), you can monitor your entire infrastructure in
18
+real time and troubleshoot problems that threaten the health of your nodes before they occur.
19
+
20
+Netdata runs permanently on all your physical/virtual servers, containers, cloud deployments, and edge/IoT devices. It
21
+runs on Linux distributions (Ubuntu, Debian, CentOS, and more), container/microservice platforms (Kubernetes clusters,
22
+Docker), and many other operating systems (FreeBSD, macOS), with no `sudo` required.
23
+
24
+<Install>
25
+ <InstallBox
26
+ to="#install-on-linux-with-one-line-installer-recommended"
27
+ os="General Linux with one-line installer (recommended)"
28
+ svg="linux" />
29
+ <InstallBox
30
+ to="#run-netdata-with-docker"
31
+ os="Run with Docker"
32
+ svg="docker" />
33
+ <InstallBox
34
+ to="/docs/agent/packaging/installer/methods/kubernetes"
35
+ os="Deploy on Kubernetes"
36
+ svg="kubernetes" />
37
+ <InstallBox
38
+ to="/docs/agent/packaging/installer/methods/macos"
39
+ os="Install on macOS"
40
+ svg="macos" />
41
+ <InstallBox
42
+ to="/docs/agent/packaging/installer/methods/packages"
43
+ os="Linux with .deb/.rpm packages"
44
+ svg="linux" />
45
+ <InstallBox
46
+ to="/docs/agent/packaging/installer/methods/kickstart-64"
47
+ os="Linux with static 64-bit binary"
48
+ svg="linux" />
49
+ <InstallBox
50
+ to="/docs/agent/packaging/installer/methods/manual"
51
+ os="Linux from Git"
52
+ svg="linux" />
53
+ <InstallBox
54
+ to="/docs/agent/packaging/installer/methods/source"
55
+ os="Linux from source"
56
+ svg="linux" />
57
+ <InstallBox
58
+ to="/docs/agent/packaging/installer/methods/offline"
59
+ os="Linux for offline nodes"
60
+ svg="linux" />
61
+</Install>
62
+
63
+## Install on Linux with one-line installer (recommended)
64
+
65
+The **recommended** way to install Netdata on a Linux node (physical, virtual, container, IoT) is our one-line
66
+[kickstart script](/packaging/installer/methods/kickstart.md). This script automatically installs dependencies and
67
+builds Netdata from its source code.
68
+
69
+Copy the script, paste it into your node's terminal, and hit `Enter` to begin the installation process.
70
+
71
+<OneLineInstall />
72
+
73
+Next, [open and explore the dashboard](#open-and-explore-the-dashboard).
74
+
75
+## Run Netdata with Docker
76
+
77
+You can also try out Netdata's capabilities in a [Docker container](/packaging/docker/README.md). Copy the following
78
+`docker run` command into your node and hit `Enter` to download and run the container.
79
+
80
+```bash
81
+docker run -d --name=netdata \
82
+ -p 19999:19999 \
83
+ -v netdataconfig:/etc/netdata \
84
+ -v netdatalib:/var/lib/netdata \
85
+ -v netdatacache:/var/cache/netdata \
86
+ -v /etc/passwd:/host/etc/passwd:ro \
87
+ -v /etc/group:/host/etc/group:ro \
88
+ -v /proc:/host/proc:ro \
89
+ -v /sys:/host/sys:ro \
90
+ -v /etc/os-release:/host/etc/os-release:ro \
91
+ --restart unless-stopped \
92
+ --cap-add SYS_PTRACE \
93
+ --security-opt apparmor=unconfined \
94
+ netdata/netdata
95
+```
96
+
97
+Next, [open and explore the dashboard](#open-and-explore-the-dashboard).
98
+
99
+## Open and explore the dashboard
100
+
101
+To start using Netdata, open a browser and navigate to `http://NODE:19999`, replacing `NODE` with either `localhost` or
102
+the hostname/IP address of a remote node.
103
+
104
+
106
+
107
+Netdata's dashboard is a single page with hundreds of preconfigured charts and thousands of metrics that update every
108
+second. Everything you see is autodetected and organized with zero configuration required.
109
+
110
+To see more charts, scroll down or use the **menu** on the right-hand side of the dashboard to navigate between
111
+**sections**, which are groups of closely related charts.
112
+
113
+
115
+
116
+## Interact with charts
117
+
118
+Every chart in the Netdata dashboard is fully interactive, and Netdata synchronizes your interactions to help you
119
+understand exactly how a node behaved in any timeframe, whether that's seconds or days.
120
+
121
+
123
+
124
+Let's cover two of the most important ways to interact with charts: panning through time and zooming.
125
+
126
+To pan through time, **click and hold** (or touch and hold) on any chart, then **drag your mouse** (or finger) to the
127
+left or right. Dragging to the right pans backward through time, while dragging to the left pans forward in time. Think
128
+of it like pushing the current timeframe off the screen so you can see what came before or after.
129
+
130
+To zoom, press and hold `Shift`, then use your mouse's scroll wheel, or a two-finger pinch if you're using a touchpad.
131
+
132
+## What's next?
133
+
134
+You've now installed Netdata, visited the dashboard at `http://NODE:19999`, learned the basics of getting around, and
135
+learned how to interact with charts by zooming and panning through time.
136
+
137
+Where you go from here is based on your use case, immediate needs, and experience with monitoring and troubleshooting.
138
+
139
+### Configuration
140
+
141
+Discover the recommended way to [configure Netdata's settings or behavior](/docs/configure/nodes.md) using our built-in
142
+`edit-config` script, then apply that knowledge to mission-critical tweaks, such as [changing how long Netdata stores
143
+metrics](/docs/store/change-metrics-storage.md).
144
+
145
+### Dashboard
146
+
147
+Learn even more about [navigating Netdata's dashboard and interacting with
148
+charts](/docs/visualize/interact-dashboards-charts.md).
149
+
150
+### Data collection
151
+
152
+If Netdata didn't autodetect all the hardware, containers, services, or applications running on your node, you should
153
+learn more about [how data collectors work](/docs/collect/how-collectors-work.md). If there's a [supported
154
+collector](/collectors/COLLECTORS.md) for metrics you need, [configure the collector](/docs/collect/enable-configure.md)
155
+or read about its requirements to configure your endpoint to publish metrics in the correct format and endpoint.
156
+
157
+### Alarms & notifications
158
+
159
+Netdata comes with hundreds of preconfigured alarms, designed by our monitoring gurus in parallel with our open-source
160
+community, but you may want to [edit alarms](/docs/monitor/configure-alarms.md) or [enable
161
+notifications](/docs/monitor/enable-notifications.md) to customize your Netdata experience.
162
+
163
+### Need to monitor multiple nodes in one place?
164
+
165
+For robust multi-node monitoring from a single interface, consider [Netdata
166
+Cloud](https://learn.netdata.cloud/docs/cloud), which streams, aggregates, and visualizes metrics from any number of
167
+nodes. It's all the same out-of-the-box, zero-configuration functionality of the open-source monitoring agent, but for
168
+any number of distributed nodes, _entirely for free_.
169
+
170
+There is an alternative for those who aren't interested in using Netdata Cloud, albeit with some required configuration.
171
+Each node can [stream](/streaming/README.md) its metrics to any other node, and the default
172
+[registry](/registry/README.md) is configurable to create a private "network" of Netdata dashboards.
docs/get/README.md
deleted
-159
@@ -1,159 +0,0 @@
1
-<!--
2
-title: "Get Netdata"
3
-description: "Time to get Netdata's monitoring and troubleshooting solution. Sign in to Cloud, download the Agent everywhere, and connect it all together."
4
-custom_edit_url: https://github.com/netdata/netdata/edit/master/docs/get/README.md
5
--->
6
-
7
-# Get Netdata
8
-
9
-import { OneLineInstall } from '../src/components/OneLineInstall/'
10
-import { Install, InstallBox } from '../src/components/InstallBox/'
11
-
12
-Netdata uses the open-source Netdata Agent and Netdata Cloud web application
13
-[together](/docs/overview/what-is-netdata.md) to help you collect every metric, visualize the health of your nodes, and
14
-troubleshoot complex performance problems. Once you've signed in to Netdata Cloud and installed the Netdata Agent on all
15
-your nodes, you can claim your nodes and see their real-time metrics on a single interface.
16
-
17
-## Sign in to Netdata Cloud
18
-
19
-If you don't already have a free Netdata Cloud account, go ahead and [create one](https://app.netdata.cloud).
20
-
21
-Choose your preferred authentication method and follow the onboarding process to create your Space.
22
-
23
-## Install the Netdata Agent
24
-
25
-The Netdata Agent runs permanently on all your physical/virtual servers, containers, cloud deployments, and edge/IoT
26
-devices. It runs on Linux distributions (**Ubuntu**, **Debian**, **CentOS**, and more), container/microservice platforms
27
-(**Kubernetes** clusters, **Docker**), and many other operating systems (**FreeBSD**, **macOS**), with no `sudo`
28
-required.
29
-
30
-> ⚠️ Many distributions ship with third-party packages of Netdata, which we cannot maintain or keep up-to-date. For the
31
-> best experience, use one of the methods described or linked to below.
32
-
33
-The **recommended** way to install the Netdata Agent on a Linux system is our one-line [kickstart
34
-script](/packaging/installer/methods/kickstart.md). This script automatically installs dependencies and builds Netdata
35
-from its source code.
36
-
37
-<OneLineInstall />
38
-
39
-Copy the script, paste it into your node's terminal, and hit `Enter`.
40
-
41
-Open your favorite browser and navigate to `http://localhost:19999` or `http://NODE:19999`, replacing `NODE` with the
42
-hostname or IP address of your system, to open the local Agent dashboard.
43
-
44
-<details>
45
-<summary>Watch how the one-line installer works</summary>
46
-<iframe width="820" height="460" src="https://www.youtube.com/embed/tVIp7ycK60A" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
47
-</details>
48
-
49
-### Other operating systems/methods
50
-
51
-Want to install Netdata on a Kubernetes cluster, with Docker, or using a different method? Not a Linux user? Choose your
52
-platform to see specific instructions.
53
-
54
-<Install>
55
- <InstallBox
56
- to="/docs/agent/packaging/installer/methods/kubernetes"
57
- img="/img/index/methods/kubernetes.svg"
58
- os="Kubernetes" />
59
- <InstallBox
60
- to="/docs/agent/packaging/docker"
61
- img="/img/index/methods/docker.svg"
62
- os="Docker" />
63
- <InstallBox
64
- to="/docs/agent/packaging/installer/methods/cloud-providers"
65
- img="/img/index/methods/cloud.svg"
66
- imgDark="/img/index/methods/cloud-dark.svg"
67
- os="Cloud providers (GCP, AWS, Azure)" />
68
- <InstallBox
69
- to="/docs/agent/packaging/installer/methods/packages"
70
- img="/img/index/methods/package.svg"
71
- imgDark="/img/index/methods/package-dark.svg"
72
- os="Linux with .deb/.rpm" />
73
- <InstallBox
74
- to="/docs/agent/packaging/installer/methods/kickstart-64"
75
- img="/img/index/methods/static.svg"
76
- imgDark="/img/index/methods/static-dark.svg"
77
- os="Linux with static 64-bit binary" />
78
- <InstallBox
79
- to="/docs/agent/packaging/installer/methods/manual"
80
- img="/img/index/methods/git.svg"
81
- imgDark="/img/index/methods/git-dark.svg"
82
- os="Linux from Git" />
83
- <InstallBox
84
- to="/docs/agent/packaging/installer/methods/freebsd"
85
- img="/img/index/methods/freebsd.svg"
86
- os="FreeBSD" />
87
- <InstallBox
88
- to="/docs/agent/packaging/installer/methods/macos"
89
- img="/img/index/methods/macos.svg"
90
- os="MacOS" />
91
-</Install>
92
-
93
-Even more options available in our [packaging documentation](/packaging/installer/README.md#alternative-methods).
94
-
95
-## Claim your node to Netdata Cloud
96
-
97
-You need to [claim](/claim/README.md) your nodes to see them in Netdata Cloud. Claiming establishes a secure TLS
98
-connection to Netdata Cloud using the [Agent-Cloud link](/aclk/README.md), and proves you have write and administrative
99
-access to that node.
100
-
101
-When you view a node in Netdata Cloud, the Agent running on that node streams metrics, metadata, and alarm status to
102
-Netdata Cloud, which in turn streams those metrics to your web browser. Netdata Cloud [does not
103
-store](/docs/store/distributed-data-architecture.md#does-netdata-cloud-store-my-metrics) or log metrics values.
104
-
105
-To claim a node, you need to run the claiming script. In Netdata Cloud, click on your Space's name, then **Manage your
106
-Space** in the dropdown. Click **Nodes** in the panel that appears. Copy the script and run it in your node's terminal.
107
-The script looks like the following, with long strings instead of `TOKEN` and `ROOM1,ROOM2`:
108
-
109
-```bash
110
-sudo netdata-claim.sh -token=TOKEN -rooms=ROOM1,ROOM2 -url=https://app.netdata.cloud
111
-```
112
-
113
-The script returns `Agent was successfully claimed.` after creating a new RSA pair and establishing the link to Netdata
114
-Cloud. If the script returns an error, try our [troubleshooting tips](/claim/README.md#troubleshooting).
115
-
116
-> 💡 Our claiming reference guide also contains instructions for claiming [Docker
117
-> containers](/claim/README.md#claim-an-agent-running-in-docker), [Kubernetes cluster parent
118
-> pods](/claim/README.md#claim-an-agent-running-in-docker), via a [proxy](/claim/README.md#claim-through-a-proxy), and
119
-> more.
120
-
121
-<details>
122
-<summary>Watch how claiming nodes works</summary>
123
-<iframe width="820" height="460" src="https://www.youtube.com/embed/UAzVvhMab8g" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
124
-</details>
125
-
126
-For more information on the claiming process, why we implemented it, and how it works, see the [claim](/claim/README.md)
127
-and [Agent-Cloud link](/aclk/README.md) reference docs.
128
-
129
-## Troubleshooting
130
-
131
-If you experience issues with installing the Netdata Agent, see our
132
-[installation](/packaging/installer/README.md#troubleshooting-and-known-issues) reference. Our
133
-[reinstall](/packaging/installer/REINSTALL.md) doc can help clean up your installation and get you back to monitoring.
134
-
135
-For Netdata Cloud issues, see the [Netdata Cloud reference docs](https://learn.netdata.cloud/docs/cloud).
136
-
137
-## What's next?
138
-
139
-At this point, you have set up your free Netdata Cloud account, installed the Netdata Agent on your node(s), and claimed
140
-one or more nodes to your Space. You're ready to start monitoring, visualizing, and troubleshooting with Netdata. We
141
-have two quickstart guides based on the scope of what you need to monitor.
142
-
143
-Interested in monitoring a single node? Check out our [single-node monitoring
144
-quickstart](/docs/quickstart/single-node.md).
145
-
146
-If you're looking to monitor an entire infrastructure with Netdata, see the [infrastructure monitoring
147
-quickstart](/docs/quickstart/infrastructure.md).
148
-
149
-Or, skip ahead to [Agent configuration](/docs/configure/nodes.md).
150
-
151
-### Related reference documentation
152
-
153
-- [Netdata Agent · Packaging & installer](/packaging/installer/README.md)
154
-- [Netdata Agent · Reinstall Netdata](/packaging/installer/REINSTALL.md)
155
-- [Netdata Agent · Update Netdata](/packaging/installer/UPDATE.md)
156
-- [Netdata Agent · Agent-Cloud link](/aclk/README.md)
157
-- [Netdata Agent · Agent claiming](/claim/README.md)
158
-
159
-[](<>)
packaging/installer/README.md
+40
-59
@@ -3,6 +3,8 @@ title: "Installation guide"
3
custom_edit_url: https://github.com/netdata/netdata/edit/master/packaging/installer/README.md
4
-->
5
6
+import { Install, InstallBox } from '../src/components/Install/'
7
+
8
# Installation guide
9
10
Netdata is a monitoring agent designed to run on all your systems: physical and virtual servers, containers, even
@@ -70,65 +72,44 @@ operating systems.
72
73
### Alternative methods
74
73
-<div class="installer-grid" markdown="1">
74
-
75
-[ Install
77
-with .deb or .rpm packages](/packaging/installer/methods/packages.md)
78
-
79
-[ Install
81
-with a pre-built static binary for 64-bit systems](/packaging/installer/methods/kickstart-64.md)
82
-
83
-[ Install
85
-Netdata on Docker](/packaging/docker/README.md)
86
-
87
-[ Install
89
-Netdata on a Kubernetes cluster](/packaging/installer/methods/kubernetes.md)
90
-
91
-[
93
-Install Netdata on cloud providers (GCP/AWS/Azure)](/packaging/installer/methods/cloud-providers.md)
94
-
95
-[ Install
97
-Netdata on macOS](/packaging/installer/methods/macos.md)
98
-
99
-[ Install
101
-Netdata on FreeBSD](/packaging/installer/methods/freebsd.md)
102
-
103
-[ Install
105
-from a Git checkout](/packaging/installer/methods/manual.md)
106
-
107
-[ Install on
109
-offline/air-gapped systems](/packaging/installer/methods/offline.md)
110
-
111
-[
113
-Installation on PFSense](/packaging/installer/methods/pfsense.md)
114
-
115
-[ Install
117
-Netdata on Synology](/packaging/installer/methods/synology.md)
118
-
119
-[ Manual
121
-installation on FreeNAS](/packaging/installer/methods/freenas.md)
122
-
123
-[ Manual
125
-installation on Alpine](/packaging/installer/methods/alpine.md)
126
-
127
-[
129
-Build manually from source](/packaging/installer/methods/source.md)
130
-
131
-</div>
75
+<Install>
76
+ <InstallBox
77
+ to="#install-on-linux-with-one-line-installer-recommended"
78
+ os="General Linux with one-line installer (recommended)"
79
+ svg="linux" />
80
+ <InstallBox
81
+ to="#run-netdata-with-docker"
82
+ os="Run with Docker"
83
+ svg="docker" />
84
+ <InstallBox
85
+ to="/docs/agent/packaging/installer/methods/kubernetes"
86
+ os="Deploy on Kubernetes"
87
+ svg="kubernetes" />
88
+ <InstallBox
89
+ to="/docs/agent/packaging/installer/methods/macos"
90
+ os="Install on macOS"
91
+ svg="macos" />
92
+ <InstallBox
93
+ to="/docs/agent/packaging/installer/methods/packages"
94
+ os="Linux with .deb/.rpm packages"
95
+ svg="linux" />
96
+ <InstallBox
97
+ to="/docs/agent/packaging/installer/methods/kickstart-64"
98
+ os="Linux with static 64-bit binary"
99
+ svg="linux" />
100
+ <InstallBox
101
+ to="/docs/agent/packaging/installer/methods/manual"
102
+ os="Linux from Git"
103
+ svg="linux" />
104
+ <InstallBox
105
+ to="/docs/agent/packaging/installer/methods/source"
106
+ os="Linux from source"
107
+ svg="linux" />
108
+ <InstallBox
109
+ to="/docs/agent/packaging/installer/methods/offline"
110
+ os="Linux for offline nodes"
111
+ svg="linux" />
112
+</Install>
113
114
## Automatic updates
115