> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/configuration/bindplane/offline-collector-package-installation-and-upgrades.md).

# Offline Collector Package Installation and Upgrades

How to set up Bindplane to host collector packages locally

{% hint style="warning" %}
**IMPORTANT**

🚧 This feature is only available in Bindplane Enterprise or Bindplane for Google. Learn more [here](https://bindplane.com/solutions/).

Offline mode is only available for self-hosted Bindplane servers. It cannot be enabled on Bindplane Cloud.
{% endhint %}

### Enable Offline Collector Package Hosting and Upgrades

This feature allows Bindplane to host the collector packages. This is used in environments where either Bindplane or the Collector system does not have external network access to GitHub.

#### Bindplane offline collector configuration

In order to use offline collector upgrades, the feature must first be enabled.

To enable offline collector upgrades, the `offline` option must be enabled. The folder where collector upgrade artifacts will be stored when uploaded may also be configured. By default, collector upgrade artifacts are stored in `/var/lib/bindplane/agent-upgrades`.

Here is an example config enabling offline mode, which has the 'offline: true' added right after the 'apiVersion' section.

```yaml
name: default
apiVersion: bindplane.observiq.com/v1

# Enables "offline" mode, which disables syncing collector versions with GitHub, and enables
# uploading upgrade packages for bindplane to host collector upgrade and install artifacts.
offline: true
auth:
  # A random uuid which is used as a shared secret between bindplane and
  # deployed collectors.
  secretKey: your-secret-key

  # Basic auth should use a username other than
  # admin along with a secure password.
  username: admin
  password: password

  # A random uuid which is used for generating web ui session cookies.
  sessionSecret: your-session-secret
network:
  # Listen on port 3001, all interfaces.
  host: 0.0.0.0
  port: '3001'

  # Endpoint for which clients and collectors will interface
  # with the server's http interface.
  remoteURL: http://bindplane.c.bindplane.internal:3001
agentVersions:
  # The path where collector upgrades are stored when uploading collector upgrade packages in offline mode.
  agentUpgradesFolder: /var/lib/bindplane/agent-upgrades
store:
  type: postgres
  postgres:
    database: bindplane
eventBus:
  type: local
logging:
  filePath: /var/log/bindplane/bindplane.log
```

### Upload a Collector Upgrade Artifact Package

Collector artifact packages can be uploaded to the Bindplane server to allow collectors to upgrade to new versions, as well as allow collectors to be installed through Bindplane while in offline mode. Packages for the Dynatrace Bindplane Distribution of OpenTelemetry (DBDOT) Collector can be found and downloaded from the [releases page of its GitHub repository](https://github.com/Dynatrace/dynatrace-bindplane-otel-collector/releases). You can download the artifact package to the Bindplane server through SSH like the example below:

```shell
curl -LO https://github.com/Dynatrace/dynatrace-bindplane-otel-collector/releases/download/v1.2.0/dynatrace-bindplane-otel-collector-v1.2.0-artifacts.tar.gz
```

To upload a collector upgrade artifact package, use the `bindplane upload agent-upgrade` command. This requires that you first set up the CLI. If you have not done so previously, you can set up a profile like the example below:

```shell
bindplane profile set "example" \
 --remote-url "http://192.168.1.10:3001" \
 --username "user" \
 --password "pass"

bindplane profile use "example"
```

{% hint style="warning" %}
Use the Bindplane credentials (the username and password in basic auth) used in the UI to set the profile
{% endhint %}

The artifact package should be downloaded onto the machine from which you are running the `bindplane` cli, which may or may not be the Bindplane server. In this example, version 1.2.0 of the DBDOT Collector is being uploaded to Bindplane:

```shell
bindplane upload agent-upgrade ./dynatrace-bindplane-otel-collector-v1.2.0-artifacts.tar.gz
```

#### How the collector type and version are determined

The collector type and version are read from the package filename when it follows the pattern `{collector-type}-v{version}[-{label}].tar.gz`:

* The collector type is everything before the version, for example `dynatrace-bindplane-otel-collector`.
* The leading `v` of the version is optional, and pre-release versions such as `v1.3.0-rc.1` are supported.
* Packaging labels after the version, such as `-artifacts`, `-artifacts-linux` or `-linux-artifacts`, are ignored.
* Both `.tar.gz` and `.tgz` packages are accepted.

If the file has been renamed, or does not follow this pattern, use the `--type` and `--version` flags. These flags always take precedence over the filename:

```shell
bindplane upload agent-upgrade ./artifacts.tar.gz --type dynatrace-bindplane-otel-collector --version v1.2.0
```

#### Upload additional platforms for an existing version

Uploading a version that has already been uploaded adds to it rather than replacing it. The platforms included in the new package replace those platforms in the existing version, and all other platforms are kept. The `SHA256SUMS` file and GPG keys are only replaced if the new package includes them.

This allows a version to be built up from several packages, for example one package per platform:

```shell
bindplane upload agent-upgrade ./dynatrace-bindplane-otel-collector-v1.2.0-artifacts-linux.tar.gz
bindplane upload agent-upgrade ./dynatrace-bindplane-otel-collector-v1.2.0-artifacts-windows.tar.gz
```

Each platform in a package must be complete. A package that contains only some of the files for a platform is rejected, and the existing version is left unchanged.

### Upload Packages for a Custom Collector Type

Upgrade artifact packages can also be uploaded for a custom collector distribution that has been registered as an Agent Type. See [Bring Your Own Collector](https://docs.bindplane.com/feature-guides/deployment-and-management/bring-your-own-collector.md) for how to create one.

{% hint style="info" %}
Uploading packages for a custom collector type requires a Bindplane Enterprise, Dynatrace Bindplane Enterprise, or Bindplane for Google Enterprise license. It is not available with a standard Bindplane for Google license. The Agent Type must already exist in the project you are uploading to.
{% endhint %}

Pass the Agent Type's `metadata.name` as the `--type` flag, or name the package `{agent-type}-v{version}-artifacts.tar.gz` so it is read from the filename:

```shell
bindplane upload agent-upgrade ./custom-otel-collector-v1.2.0-artifacts.tar.gz --type custom-otel-collector
```

The package must use the same file layout as the DBDOT Collector artifacts package, with files named after the Agent Type. `{version}` includes the leading `v`, for example `v1.2.0`:

* `{agent-type}-{version}-SHA256SUMS`, containing the SHA256 sums of the upgrade packages.
* For each platform, the upgrade package (for example `{agent-type}-{version}-linux-amd64.tar.gz` or `{agent-type}-{version}-windows-amd64.zip`) and its installer (`install_unix.sh`, `install_macos.sh`, or `{agent-type}.msi`).
* For Linux platforms, the `.deb` and `.rpm` packages, for example `{agent-type}_{version}_linux_amd64.deb`.

To have Bindplane read the custom collector's versions from uploaded packages instead of syncing them from GitHub, set `versionClient: offline` in the Agent Type's spec:

```yaml
apiVersion: bindplane.observiq.com/v1
kind: AgentType
metadata:
  name: custom-otel-collector
spec:
  versionClient: offline
  platformArchSet:
    - platform: linux
      arch: amd64
```

### Delete Old Collector Artifact Packages

Collector versions and agent artifact packages can be removed using the `bindplane delete agent-version` command:

```shell
bindplane delete agent-version dynatrace-bindplane-otel-collector-v1.2.0
```

The name of a collector version is `{collector-type}-{version}`, so a custom collector version is deleted the same way:

```shell
bindplane delete agent-version custom-otel-collector-v1.2.0
```

This will delete the version from Bindplane and remove the unpacked artifact package from the disk of the Bindplane server.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bindplane.com/configuration/bindplane/offline-collector-package-installation-and-upgrades.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
