Manual Distribution

Distributing the Agent

To enable automatic updates, the agent must be distributed through an S3 storage service. This is handled automatically through oclif and is configured in the package.json file under the oclif.s3 key.

Rack Manage uses Cloudflare R2 rather than AWS S3 for distribution. While oclif supports non-AWS S3 storage, there is some additional configuration required to use it.

Cloudflare R2 Configuration

The Rack Manage Agent R2 server is configured to use the rmagent bucket on the agent.rackmanage.io domain. This domain is registered in the Rack Manage Subdomain Router and is excluded in the banned names list of the cloud functions repository.

First, you must set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to the Cloudflare R2 credentials. You must also set the AWS_ENDPOINT_URL_S3 variable to the Cloudflare R2 endpoint.

export AWS_ACCESS_KEY_ID=<READ_WRITE_ACCESS_KEY>
export AWS_SECRET_ACCESS_KEY=<SECRET_ACCESS_KEY>
export AWS_ENDPOINT_URL_S3=https://<ACCOUNT_ID>.r2.cloudflarestorage.com

Uploading Builds

Once these environment variables are set, you can upload the agent to Cloudflare R2 by running the following command:

oclif upload <type>

Where <type> is the type of file to upload, such as tarballs, macos, or win.

Finally, you can publish the agent to the Cloudflare R2 distribution by running the following command:

oclif promote --channel <channel> --version <version> --sha <sha> --indexes --xz

Where <channel> is the release channel to publish to, such as stable or beta, <version> is the version number, and <sha> is the 7 character git commit hash.

By default, this command will only publish tarballs. To publish other types of files, you must specify the type with the -m, or -w flags for macos, and win files, respectively.

Debian Packages

The Debian commands oclif upload deb and oclif promote -d do not work properly (see oclif issue #1074) due to the use of ./ as the Debian distribution, where S3 does not support folders named ..

To work around this, you can manually upload the Debian package to Cloudflare R2 through the aws CLI with the following command:

aws s3 cp dist/deb s3://rmagent/apt --recursive 

In order to handle the cases where Debian attempts to download the package from the ./ directory, a redirect is setup in the Rack Manage Subdomain Router to redirect requests from https://agent.rackmanage.io/apt/./ to https://agent.rackmanage.io/apt/. Note that the apt repository does not support release channels and only the latest version is available.

The Debian repository also includes two additional files, Release.key and install.sh which are used to add the GPG key to the system, and automate the installation of the package. install.sh is located in the scripts directory, while Release.key is not stored in the repository. Both files are automatically uploaded / generated during the CircleCI build process.

To update install.sh and Release.key manually, run the following commands:

aws s3 cp scripts/install.sh s3://rmagent/install.sh

aws s3 cp Release.key s3://rmagent/apt/Release.key