[id="{beatname_lc}-installation-configuration"]
== {beatname_uc} quick start: installation and configuration

++++
<titleabbrev>Quick start: installation and configuration</titleabbrev>
++++

This guide describes how to get started quickly collecting uptime data about
your hosts. You'll learn how to:

* install {beatname_uc}
* specify the protocols to monitor
* send uptime data to {es}
* visualize the uptime data in {kib}

[role="screenshot"]
image::./images/heartbeat-statistics.png[{beatname_uc} HTTP monitoring dashboard]

[float]
=== Before you begin

You need {es} for storing and searching your data, and {kib} for visualizing and
managing it.

include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[]

[float]
[[installation]]
=== Step 1: Install Heartbeat

Unlike most Beats, which you install on edge nodes, you typically install
Heartbeat as part of a monitoring service that runs on a separate machine
and possibly even outside of the network where the services that you want to
monitor are running.

To download and install {beatname_uc}, use the commands that work with your
system:

include::{libbeat-dir}/tab-widgets/install-widget.asciidoc[]

[float]
[[other-installation-options]]
==== Other installation options

* <<setup-repositories,APT or YUM>>
* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page]
* <<running-on-docker,Docker>>

[float]
[[set-connection]]
=== Step 2: Connect to the {stack}

include::{libbeat-dir}/shared/connecting-to-es.asciidoc[]

[float]
[[configuration]]
=== Step 3: Configure Heartbeat monitors

Heartbeat provides monitors to check the status of hosts at set intervals.
Heartbeat currently provides monitors for ICMP, TCP, and HTTP (see
<<heartbeat-overview>> for more about these monitors).

You configure each monitor individually. In +{beatname_lc}.yml+, specify the
list of monitors that you want to enable. Each item in the list begins with a
dash (-). The following example configures Heartbeat to use two monitors, an
`icmp` monitor and a `tcp` monitor:

[source,yaml]
----------------------------------------------------------------------
heartbeat.monitors:
- type: icmp
  schedule: '*/5 * * * * * *' <1>
  hosts: ["myhost"]
  id: my-icmp-service
  name: My ICMP Service
- type: tcp
  schedule: '@every 5s' <2>
  hosts: ["myhost:12345"]
  mode: any <3>
  id: my-tcp-service
- type: http
  schedule: '@every 5s'
  urls: ["http://example.net"]
  service_name: apm-service-name <4>
  id: my-http-service
  name: My HTTP Service
----------------------------------------------------------------------
<1> The `icmp` monitor is scheduled to run exactly every 5 seconds (10:00:00,
10:00:05, and so on). The `schedule` option uses a cron-like syntax based on
https://github.com/gorhill/cronexpr#implementation[this `cronexpr` implementation].
<2> The `tcp` monitor is set to run every 5 seconds from the time when Heartbeat
was started. Heartbeat adds the `@every` keyword to the syntax provided by the
`cronexpr` package.
<3> The `mode` specifies whether to ping one IP (`any`) or all resolvable IPs
<4> The `service_name` field can be used to integrate heartbeat with elastic APM via the Uptime UI.

include::{libbeat-dir}/shared/config-check.asciidoc[]

[float]
[[configurelocation]]
=== Step 4: Configure the Heartbeat location

Heartbeat can be deployed in multiple locations so that you can detect 
differences in availability and response times across those locations.
Configure the Heartbeat location to allow {kib} to display location-specific
information on Uptime maps and perform Uptime anomaly detection based
on location.

To configure the location of a Heartbeat instance, modify the 
`add_observer_metadata` processor in +{beatname_lc}.yml+.  The following 
example specifies the `geo.name` of the `add_observer_metadata` processor as
`us-east-1a`:

[source,yaml]
----------------------------------------------------------------------
# ============================ Processors ============================

processors:
  - add_observer_metadata:
      # Optional, but recommended geo settings for the location Heartbeat is running in
      geo: <1>
        # Token describing this location
        name: us-east-1a <2>
        # Lat, Lon "
        #location: "37.926868, -78.024902" <3>
----------------------------------------------------------------------
<1> Uncomment the `geo` setting.
<2> Uncomment `name` and assign the name of the location of the Heartbeat server.
<3> Optionally uncomment `location` and assign the latitude and longitude.

include::{libbeat-dir}/shared/config-check.asciidoc[]

[float]
[[setup-assets]]
=== Step 5: Set up assets

{beatname_uc} comes with predefined assets for parsing, indexing, and
visualizing your data. To load these assets:

. Make sure the user specified in +{beatname_lc}.yml+ is
<<privileges-to-setup-beats,authorized to set up {beatname_uc}>>.

. From the installation directory, run:
+
--
include::{libbeat-dir}/tab-widgets/setup-widget.asciidoc[]
--
+
`-e` is optional and sends output to standard error instead of the configured log output.

This step loads the recommended {ref}/indices-templates.html[index template] for writing to {es}.
It does not install {beatname_uc} dashboards.  Heartbeat dashboards and
installation steps are available in the
https://github.com/elastic/uptime-contrib[uptime-contrib] GitHub repository.

[TIP]
=====
A connection to {es} (or {ess}) is required to set up the initial
environment. If you're using a different output, such as {ls}, see
<<load-template-manually>>.
=====

[float]
[[start]]
=== Step 6: Start Heartbeat

Before starting {beatname_uc}, modify the user credentials in
+{beatname_lc}.yml+ and specify a user who is
<<privileges-to-publish-events,authorized to publish events>>.

To start {beatname_uc}, run:

:requires-sudo:
include::{libbeat-dir}/tab-widgets/start-widget.asciidoc[]
:requires-sudo!:

Heartbeat is now ready to check the status of your services and send
events to your defined output.

[float]
[[view-data]]
=== Step 7: View your data in {kib}

{beatname_uc} comes with pre-built {kib} dashboards and UIs for visualizing the
status of your services. The dashboards are available in the
https://github.com/elastic/uptime-contrib[uptime-contrib] GitHub repository.

If you loaded the dashboards earlier, open them now.

include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards]

[float]
=== What's next?

Now that you have your uptime data streaming into {es}, learn how to unify your
logs, metrics, uptime, and application performance data.

include::{libbeat-dir}/shared/obs-apps.asciidoc[]

// Add Javascript and CSS for tabbed panels
include::{libbeat-dir}/tab-widgets/code.asciidoc[]
