# 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.

### 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>