---

id: version-0.20.0-incubating-deployment-api-server title: The Heron API Server sidebar_label: The Heron API Server original_id: deployment-api-server

The Heron API server is a necessary component

If you‘re running Heron locally on your laptop, you won’t need to run the Heron API server separately; its functions will be handled automatically.

Installation

The Heron API server executable (heron-apiserver) is installed automatically when you install the Heron tools.

Running the Heron API server

You can start up the Heron API server using the heron-apiserver command. When you do so you'll need to specify two things:

• A base template for the scheduler that the API server will be interacting with
• A cluster name for the Heron cluster

Here's an example:

$ heron-apiserver \
  --base-template mesos \
  --cluster sandbox

Base templates

The Heron API server works by accepting incoming commands from the Heron CLI tool and interacts with a variety of Heron components, including:

• a scheduler (Mesos, Aurora, the local filesystem, etc.)
• an uploader (Amazon S3, the local filesystem, etc.)

When you install the Heron tools, a directory will automatically be created in ~/.herontools/conf on MacOS and /usr/local/herontools/conf on other platforms. That directory contains a number of base templates for all of the currently supported schedulers. Modify the configuration for your scheduler, for example Mesos using the YAML files in the mesos folder, and then select the proper base template using the --base-template flag. Here's an example for Mesos:

$ heron-apiserver \
  --base-template mesos \
  --cluster my-cluster

For a full guide to Heron configuration, see Configuring a cluster.

Cluster name

In addition to specifying a base template when starting up the API server, you also need to specify a name for the cluster that the Heron API server will be serving. Here's an example:

$ heron-apiserver \
  --base-template mesos \
  --cluster us-west-prod

{{< alert “api-server-cluster-name” >}}

Other options

In addition to specifying a base template and cluster name, you can also specify:

Flag	Description
--config-path	A non-default path to a base configuration
--port	The port to bind to (the default is 9000)

Configuration overrides

When you specify a base template when running the Heron API server, the server will use whatever configuration is found in the template files. You can override configuration on a per-parameter basis, however, using the -D flag. Here's an example:

$ heron-apiserver \
  --base-template aurora \
  --cluster us-west-prod \
  -D heron.statemgr.connection.string=zk-1:2181,zk-2:2181,zk-3:2181 \
  -D heron.class.uploader=com.acme.uploaders.MyCustomUploader