> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up Honeycomb Refinery

> Install and configure Refinery for the first time, connect it to your data pipeline, and prepare it to start making tail-based sampling decisions.

export const refinery = {
  "version": "2.9.4"
};

<Note>
  Just getting started with Refinery?

  Check out the [Introduction to Refinery](https://academy.honeycomb.io/app/courses/96b6353d-28da-4b73-9a45-e72db585cb7a) course in the [Honeycomb Academy](https://academy.honeycomb.io/)! This guided tour walks you through configuring and managing sampling strategies with Refinery, so you can get hands-on experience before deploying to your production environment.
</Note>

Set up Honeycomb Refinery on Kubernetes, or in Linux x86-64/AMD64 and Linux ARM64 environments.

Refinery is designed to sit within your infrastructure where all sources of Honeycomb events can reach it.
A standard deployment will have a cluster of servers running Refinery accessible via a load balancer.
Refinery instances must be able to communicate with each other to concentrate traces on single servers.

For the quickest way to get started using Refinery:

1. Meet [system requirements](#system-requirements) before starting
2. [Download and install](#getting-started) the latest version of Refinery
3. [Set up your cluster](#set-up-your-refinery-cluster) of Refinery processes
4. Customize your [configuration and sampling rules](#refinery-configuration)

## System Requirements

To begin, your Refinery cluster requires a minimum of:

* a `linux/amd64` or `linux/arm64` operating system
* 2GB RAM for each server used
* Access to 2 cores for each server used

In many cases, Refinery only needs one node.
If experiencing a large volume of traffic, you may need multiple Refinery nodes, and likely need a small Redis instance to handle scaling.

We recommend increasing the amount of RAM and the number of cores after your initial set-up.
Use our [scale](/manage-data-volume/sample/honeycomb-refinery/scale-size/) and [troubleshooting](/troubleshoot/common-issues/refinery/) documentation to learn more.

## Getting Started

<Tabs>
  <Tab title="Kubernetes">
    The recommended way to run Refinery on Kubernetes is with its [Helm chart](https://artifacthub.io/packages/helm/honeycomb/refinery).

    1. Add the Honeycomb Helm repository.

       ```shell theme={}
       helm repo add honeycomb https://honeycombio.github.io/helm-charts
       ```

    2. Update the Honeycomb repository to ensure that `helm` has the latest chart versions.

       ```shell theme={}
       helm repo update honeycomb
       ```

    3. Install the latest version of the Refinery Helm chart with default values.

       ```shell theme={}
       helm install refinery honeycomb/refinery
       ```

    Helm chart versions and Refinery versions are not in sync.
    For example, Refinery chart version `2.15.5` installs Refinery version `2.9.4`.
    When installing a specific version, you can check the [Refinery Helm chart documentation](https://artifacthub.io/packages/helm/honeycomb/refinery) to see which chart version installs the version of Refinery you want.
  </Tab>

  <Tab title="Standard">
    <Note>
      Running on containers?
      We have a Docker image available on [Docker Hub](https://hub.docker.com/r/honeycombio/refinery).
    </Note>

    Find our [latest release of Refinery for your operating system and architecture on GitHub](https://github.com/honeycombio/refinery/releases/latest).

    Use the command line script below to download the latest released `.rpm` asset for `x86_64` from GitHub, install, and then run Refinery:

    ```shell theme={}
    curl -L -O https://github.com/honeycombio/refinery/releases/download/latest/refinery-2.9.4.x86_64.rpm
    rpm -ivh refinery-2.9.4.x86_64.rpm
    systemctl start refinery.service
    ```

    In the above example, we use `systemctl` to run the [Refinery service](https://github.com/honeycombio/refinery/blob/main/refinery.service).
    Logs can be found at `/var/log/journal/refinery.service.log`.
  </Tab>
</Tabs>

### Command Line Flags

The Refinery executable has the following command line flags:

`-c`, `--config=`
: Path to config file (default: `/etc/refinery/refinery.yaml`)

`-r`, `--rules_config=`
: Path to rules config file (default: `/etc/refinery/rules.yaml`)

`-v`, `--version`
: Print version number and exit

`-d`, `--debug`
: If enabled, runs debug service (runs on the first open port between `localhost:6060` and `:6069` by default).
Can be used with a debug service, which allows you to use [`pprof`](https://github.com/google/pprof) to visualize and analyze profiling data.

`-h`, `--help`
: Show help message

## Set Up Your Refinery Cluster

<Note>
  Be sure to keep configuration in-sync between the Refinery processes, so that your traces are consistent.
</Note>

Ensure that your Refinery cluster(s) meet the [minimum system requirements](#system-requirements).

We recommend that your list of Refinery peers be configured through Redis (see [Redis-based peer management](/manage-data-volume/sample/honeycomb-refinery/configure/#redis-peer-management)).
The Redis server can be small since it only maintains the list of peers.
Should the Redis service become unavailable, Refinery instances will continue to use their last known peer list for inter-peer communication.

<Note>
  Refinery does not currently support Redis Cluster or the Redis Sentinel protocol.
</Note>

For services that are currently sending events directly to Honeycomb's API, update these services' Honeycomb `API Host` property to be the URL for your Refinery cluster's load balancer to start sampling events with Refinery.

## Refinery Configuration

The default configuration at installation will allow you to run Refinery without any other changes.
Be sure to run Refinery in [Dry Run Mode](/manage-data-volume/sample/honeycomb-refinery/sampling-methods/#run-refinery-in-dry-run-mode) to verify your configuration before dropping traffic.

To tune Refinery to your needs, Refinery's configuration requires additional changes in two files:

* `config.yaml` contains **general configuration** options, such as Network, Access Key, and Peer Management settings.
  Read our [documentation on all available configuration options](/manage-data-volume/sample/honeycomb-refinery/configure/).

* `rules.yaml` contains **sampling rules configuration**.
  Read our [documentation on all supported sampling methods and their associated configuration](/manage-data-volume/sample/honeycomb-refinery/sampling-methods/).

As you modify, check out our [scale](/manage-data-volume/sample/honeycomb-refinery/scale-size/) and [troubleshooting](/troubleshoot/common-issues/refinery/) documentation for recommendations and strategies.