# Install using the Tarball

This guide describes how to install the **Particle Horizon `pho-collector`** on Linux using the `.tar.gz` archives.

`pho-collector` is a standalone OpenTelemetry Collector distribution.

## Supported Linux architectures

Release archives are produced for:

<table><caption class="sr-only">Supported Linux architectures</caption><thead><tr><th scope="col">Architecture</th><th scope="col">Archive suffix</th></tr></thead><tbody><tr><td>AMD64 / x86-64</td><td><code>Linux_x86_64.tar.gz</code></td></tr><tr><td>ARM64 / AArch64</td><td><code>Linux_arm64.tar.gz</code></td></tr></tbody></table>

The archive contains the following runtime layout:

```
particle_horizon/
├── SOFTWARE/
│   └── pho-collector-<version>-linux-<arch>/
│       ├── BUILD_INFO.txt
│       ├── THIRDPARTY_NOTICES
│       └── bin/
│           └── pho-collector
├── pho-collector --> SOFTWARE/pho-collector-<version>-linux-<arch>/bin/pho-collector
├── local_config/
│   └── pho-collector/
│       ├── config.yaml
│       └── pho-collector.conf
├── local_data/
│   └── pho-collector/
└── logs/
    └── pho-collector/
```

The intended installation root on Linux is:

```
/opt/particle_horizon
```

## Prerequisites

This guide assumes that you have already acquired and placed the archive on the target machine.

The installation commands in this guide require:

-   a supported 64-bit Linux system;
-   `tar`;
-   `systemd` if the collector will be installed as a system service;
-   `sudo` or root access to install under `/opt`.

You can check the current system architecture with:

```
uname -m
```

Typical results are:

```
x86_64
```

or:

```
aarch64
```

## 1\. Extract the archive

Create a temporary extraction directory:

```
INSTALL_TMP="$(mktemp -d)"
```

Extract the release:

```
tar -xzf "${ARCHIVE}" -C "${INSTALL_TMP}"
```

Inspect the contents:

```
find "${INSTALL_TMP}/particle_horizon" -maxdepth 4 -print
```

## 2\. Create the service account

When running `pho-collector` as a system service, create a dedicated system account:

```
sudo useradd \
  --system \
  --home-dir /opt/particle_horizon \
  --shell /usr/sbin/nologin \
  pho-collector
```

If the account already exists, `useradd` will report that condition and no further action is required.

You can confirm the account with:

```
getent passwd pho-collector
```

## 3\. Install the collector

Create the installation directory:

```
sudo mkdir -p /opt/particle_horizon
```

Copy the contents of the extracted `particle_horizon` directory into it:

```
sudo cp -a \
  "${INSTALL_TMP}/particle_horizon/." \
  /opt/particle_horizon/
```

The collector should now be available through the stable path:

```
/opt/particle_horizon/pho-collector
```

Check it:

```
/opt/particle_horizon/pho-collector --help
```

The stable path points at the collector binary beneath the version-specific `SOFTWARE` directory.

## 4\. Set directory ownership

The collector service runs under the `pho-collector` user and group.

Give the service write access to its runtime data and log directories:

```
sudo chown -R pho-collector:pho-collector \
  /opt/particle_horizon/local_data/pho-collector \
  /opt/particle_horizon/logs/pho-collector
```

The configuration can remain owned by root:

```
sudo chown -R root:root \
  /opt/particle_horizon/local_config/pho-collector
```

Ensure the collector can read its configuration:

```
sudo chmod 0755 /opt/particle_horizon/local_config
sudo chmod 0755 /opt/particle_horizon/local_config/pho-collector
sudo chmod 0644 /opt/particle_horizon/local_config/pho-collector/config.yaml
sudo chmod 0644 /opt/particle_horizon/local_config/pho-collector/pho-collector.conf
```

## 5\. Configure the collector

The default configuration is installed at:

```
/opt/particle_horizon/local_config/pho-collector/config.yaml
```

Edit it as required for the environment:

```
sudo vi /opt/particle_horizon/local_config/pho-collector/config.yaml
```

The supplied environment file is:

```
/opt/particle_horizon/local_config/pho-collector/pho-collector.conf
```

By default it contains settings equivalent to:

```
OTELCOL_OPTIONS="--config=/opt/particle_horizon/local_config/pho-collector/config.yaml"
GOMAXPROCS=2
```

Additional collector command-line options can be added to `OTELCOL_OPTIONS`.

For example:

```
OTELCOL_OPTIONS="--config=/opt/particle_horizon/local_config/pho-collector/config.yaml --set=service.telemetry.logs.level=info"
```

## 6\. Test the collector manually

Before creating the service, run the collector interactively:

```
sudo -u pho-collector \
  /opt/particle_horizon/pho-collector \
  --config=/opt/particle_horizon/local_config/pho-collector/config.yaml
```

If the configuration is valid, the collector should start and begin initialising its configured receivers, processors, exporters, extensions, and pipelines.

Stop the interactive process with `Ctrl+C`.

## 7\. Install the systemd service

Create:

```
/etc/systemd/system/pho-collector.service
```

with the following content:

```
[Unit]
Description=Particle Horizon Collector
After=network.target

[Service]
EnvironmentFile=/opt/particle_horizon/local_config/pho-collector/pho-collector.conf
ExecStart=/opt/particle_horizon/pho-collector $OTELCOL_OPTIONS
ExecReload=/bin/kill -HUP $MAINPID
KillMode=mixed
Restart=on-failure
Type=simple
User=pho-collector
Group=pho-collector
WorkingDirectory=/opt/particle_horizon

[Install]
WantedBy=multi-user.target
```

For example:

```
sudo tee /etc/systemd/system/pho-collector.service >/dev/null <<'EOF'
[Unit]
Description=Particle Horizon Collector
After=network.target

[Service]
EnvironmentFile=/opt/particle_horizon/local_config/pho-collector/pho-collector.conf
ExecStart=/opt/particle_horizon/pho-collector $OTELCOL_OPTIONS
ExecReload=/bin/kill -HUP $MAINPID
KillMode=mixed
Restart=on-failure
Type=simple
User=pho-collector
Group=pho-collector
WorkingDirectory=/opt/particle_horizon

[Install]
WantedBy=multi-user.target
EOF
```

Reload systemd:

```
sudo systemctl daemon-reload
```

Enable the collector at boot:

```
sudo systemctl enable pho-collector
```

Start it:

```
sudo systemctl start pho-collector
```

## 8\. Verify the service

Check the service state:

```
sudo systemctl status pho-collector
```

A healthy installation should show:

```
Active: active (running)
```

Follow the systemd journal with:

```
sudo journalctl -u pho-collector -f
```

You can also inspect the installed binary:

```
readlink -f /opt/particle_horizon/pho-collector
```

This should resolve to a version-specific path similar to:

```
/opt/particle_horizon/SOFTWARE/pho-collector-1.2.3-linux-amd64/bin/pho-collector
```

## Upgrading

The archive layout keeps the executable beneath a version-specific directory while exposing a stable path at:

```
/opt/particle_horizon/pho-collector
```

This makes upgrades possible without replacing the existing version directory.

### Before upgrading to v0.4.0

Collector v0.4.0 no longer includes the JMX receiver. Check the active configuration for `jmx` receiver instances before stopping the existing service:

```
grep -nE '^[[:space:]]*jmx(/[^:]+)?:' \
  /opt/particle_horizon/local_config/pho-collector/config.yaml
```

If the command returns a receiver, remove that receiver and every pipeline reference to it, or arrange an alternative JMX collection method. The v0.4.0 Collector cannot start while its configuration references the removed component.

Validate the complete configuration with the new binary before switching the stable executable path or starting the system service.

### 1\. Download and extract the new version

Follow the procedure above for the new release.

### 2\. Stop the collector

```
sudo systemctl stop pho-collector
```

### 3\. Back up the current configuration

Because the archive contains a default `config.yaml`, preserve the site’s existing configuration before copying the new archive:

```
sudo cp \
  /opt/particle_horizon/local_config/pho-collector/config.yaml \
  /opt/particle_horizon/local_config/pho-collector/config.yaml.bak
```

If `pho-collector.conf` has been customised, back that up as well:

```
sudo cp \
  /opt/particle_horizon/local_config/pho-collector/pho-collector.conf \
  /opt/particle_horizon/local_config/pho-collector/pho-collector.conf.bak
```

### 4\. Install the new archive

Copy the new `particle_horizon` tree into `/opt`:

```
sudo cp -a \
  "${INSTALL_TMP}/particle_horizon/." \
  /opt/particle_horizon/
```

### 5\. Restore or merge configuration

Restore the site’s configuration if required:

```
sudo cp \
  /opt/particle_horizon/local_config/pho-collector/config.yaml.bak \
  /opt/particle_horizon/local_config/pho-collector/config.yaml
```

Where a release introduces configuration changes, merge the previous site configuration into the newly supplied configuration instead of restoring it blindly.

### 6\. Start the new version

```
sudo systemctl start pho-collector
```

Verify it:

```
sudo systemctl status pho-collector
```

and:

```
readlink -f /opt/particle_horizon/pho-collector
```

Once the new release has been validated, older directories beneath:

```
/opt/particle_horizon/SOFTWARE/
```

can be removed if they are no longer required for rollback.

## Uninstalling

Stop and disable the service:

```
sudo systemctl disable --now pho-collector
```

Remove the service definition:

```
sudo rm -f /etc/systemd/system/pho-collector.service
sudo systemctl daemon-reload
```

Remove the application:

```
sudo rm -rf /opt/particle_horizon
```

Optionally remove the service account:

```
sudo userdel pho-collector
```

## File locations

<table><caption class="sr-only">File locations</caption><thead><tr><th scope="col">Purpose</th><th scope="col">Location</th></tr></thead><tbody><tr><td>Stable executable</td><td><code>/opt/particle_horizon/pho-collector</code></td></tr><tr><td>Versioned software</td><td><code>/opt/particle_horizon/SOFTWARE/</code></td></tr><tr><td>Collector configuration</td><td><code>/opt/particle_horizon/local_config/pho-collector/config.yaml</code></td></tr><tr><td>Service environment</td><td><code>/opt/particle_horizon/local_config/pho-collector/pho-collector.conf</code></td></tr><tr><td>Runtime data</td><td><code>/opt/particle_horizon/local_data/pho-collector/</code></td></tr><tr><td>Collector logs</td><td><code>/opt/particle_horizon/logs/pho-collector/</code></td></tr><tr><td>systemd unit</td><td><code>/etc/systemd/system/pho-collector.service</code></td></tr></tbody></table>