---
title: Installing a collector
slug: how-tos/Iv4_-installing-a-collector
docTags: GOo15ntkoXThxPf_Z8vVm
createdAt: 2025-09-04T15:04:38.938Z
---

The installation of the collector is done by running the install command on the collector binary. The install process will copy the binary to the correct directory and create a service on the host system (=server running the collector).

## Requirements

### Access and permissions

- Permissions in Factry Historian to *manage* collectors. See [Privileges](docId\:K2NnYEcUxqQsiuCLmpfKH).
- Configured Factry Historian [API](docId\:JWpo8qZsond29MHGLErEa) settings.
- Administration rights on the host system where the collector will run.

### Host system

- Host operating system:
  - Linux (32-bit, 64-bit or ARM architecture)
  - Windows ≥ 10 (32-bit or 64-bit architecture)
- Preferably the same machine that hosts the data source, or as close to the production data source as possible. This keeps latency to a minimum when collecting data points.

:::hint{type="info"}
Depending on the type of collector, a specific OS/CPU build may not be available. Refer to the Download section in the [Factry portal](https://portal.factry.cloud) for a list of build architectures available for each collector.
:::

### Server resources

- At least 5GB free disk space (3GB for collector buffering / store and forward, plus 2GB head room).
- At least 2GB free RAM (up to 500MB per collector depending on the collector type, plus 1.5GB head room).

### Time synchronisation

- Access from the collector server to a local or public NTP server.
- NTP time synchronisation configured on the collector server, typically handled by a domain controller.

### Network

- Ability to open a TCP connection from the host system to the Factry Historian server on port 8001 (using gRPC).
- Connectivity from the host system to the data source endpoint, e.g. OPC-UA server, MQTT broker, REST API.

:::hint{type="info"}
The connection from the host system to Factry Historian is outbound only for security purposes
:::

## Creating a collector in Factry Historian

In Factry Historian, visit the **Collectors** page and click the **+ Create collector** button.

1. Enter a **unique** name
2. *Optionally enter a description*
3. *Optionally choose a default database*
4. Click **Submit**

A success message should appear signifying the collector has been created. If something went wrong, an error message will appear.

## Generate a token

1. Select the collector you have just created
2. Press the **Generate token** button

After pressing the button a modal will open with the generated collector token.

Click **Copy to clipboard**. You will pass this token as a flag with the install command.

For your information: the collector token contains 4 pieces of important information for the collector

- Historian server URL
- Historian server REST port
- Historian server GRPC port
- Collector UUID

:::hint{type="warning"}
Collectors are linked to a corresponding collector user. You can invalidate the generated token in the user overview. Creating a new token will also invalidate the old token after 24 hours.
:::

## Getting the binary

1. Navigate to [https://portal.factry.cloud](https://portal.factry.cloud)
2. Login with your credentials
3. Once logged in, click Downloads in the header menu
4. In the Downloads panel:
   - Select a release channel (`Stable`)
   - Select a product (collector type)
   - Select a version
   - Select the OS/Platform of the host system
5. Click **Download** to download the binary
6. Manually copy it to the host system (location does not matter).

## Start the binary with the collector token

Now that the collector binary is on the host system and a collector token is generated, the collector can be installed.

Open a terminal with administrator rights (powershell or CMD) and navigate to the folder where the collector binary is located e.g. `C:\Users\MyUser\Documents\factry`

```powershell
cd "C:\Users\MyUser\Documents\factry"
```

The following command will register the collector as a system service and start the collector. Using the information in the token, the collector will establish a connection with the Factry Historian server:

- replace the filename with your collector binary filename
- replace the token after `-t` with your token (use the surrounding `"`)

**Example on windows**

```powershell
  .\factry-opcua-collector_v2.2.1_windows-x64 install -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjgwMDAiLCJleHAiOjI0MzcyMDI0MDcsImdycGMtcG9ydCI6IjgwMDEiLCJpYXQiOjE2NDg4MDI0MDcsImlzcyI6ImZhY3RyeS5pbyIsInJlc3QtcG9ydCI6IjgwMDAiLCJ1dWlkIjoiNjgxZmZiNjQtYjE4Ny0xMWVjLWJlNWYtMDI0MmFjMTgwMDAzIn0.RQlzFoi7I-793-sRIe8bGcQAM5fxQ7lHHkUCVcwxNu8"
```

**Example on linux**

```bash
  chmod +x factry-opcua-collector_v2.2.1_linux-x64
  sudo ./factry-opcua-collector_v2.2.1_linux-x64 install -t "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjgwMDAiLCJleHAiOjI0MzcyMDI0MDcsImdycGMtcG9ydCI6IjgwMDEiLCJpYXQiOjE2NDg4MDI0MDcsImlzcyI6ImZhY3RyeS5pbyIsInJlc3QtcG9ydCI6IjgwMDAiLCJ1dWlkIjoiNjgxZmZiNjQtYjE4Ny0xMWVjLWJlNWYtMDI0MmFjMTgwMDAzIn0.RQlzFoi7I-793-sRIe8bGcQAM5fxQ7lHHkUCVcwxNu8"
```

**Install help**

```bash
Usage:
  opc-ua-collector-v2.2.1 install [flags]

Flags:
  -e, --env stringToString   Environmental value overrides e.g. BATCH_SIZE=200 (default [])
  -h, --help                 help for install
  -i, --installDir string    the directory where the collector will be installed (default "/opt/factry")
  -t, --token string         Collector token
  -u, --user string          The user used to run the service (default "factry-system-user")
  -w, --workDir string       the working directory for the collector (default "/var/opt/factry")
```

### Expected outcome

When the collector is successfully installed and connected to Factry Historian, in the **Factry Historian webpage > Collectors**, the collector shows an <font color="#46abdd">**initial state**</font>.

See the [Troubleshooting](docId\:Iv4_SD56TdxcqKRKCj4kv) section below if this is not the case.

:::hint{type="info"}
When wanting to move the collector to another host system, refer to the [Moving a collector](docId\:eLHEQzTNa06TW1Tp69b1c) documentation.
:::

## Configure the collector

See [Collectors, protocols and data formats](docId:3fYs7rs2FLI2rDgV2zV7g) to configure your collector, depending on the collector type.

## Troubleshooting

### The collector does not show an Initial state in Factry Historian

**Plausible causes:**

1. The **URL** in the Factry Historian [API](docId\:JWpo8qZsond29MHGLErEa) settings is **not** the URL used by the collector.
   The collector connection URL is configured under **Configuration > General > API > URL**. If this URL is incorrect, update it, regenerate the collector token, and rerun the installation command.
2. The API URL of Factry Historian may be correct but **not reachable** from the collector host. Verify the required network rules with your IT department.

:::hint{type="info"}
Can't spot your error? Contact Factry support.
:::