Install the Stairwell Forwarder via APT (Debian/Ubuntu)

Stairwell publishes a signed Debian APT repository at downloads.stairwell.com. This lets you install and upgrade the forwarder on Debian-based Linux hosts using standard package tooling, and is the recommended install path for customers who manage hosts with configuration management (Ansible, Salt, Chef, etc.) or prefer to keep the forwarder alongside other system packages.

Prerequisites

• A Debian-based Linux host
• curl and gpg installed
• sudo / root access on the target host
• Stairwell forwarder credentials, available in the Stairwell console under Settings → Forwarders

Add the Stairwell repository

Run these two commands on the target host. The first imports Stairwell's signing key; the second registers the repository.

curl -fsSL https://downloads.stairwell.com/debian/stairwell-key.pgp \
  | sudo gpg --dearmor -o /usr/share/keyrings/stairwell-archive.gpg

echo "deb [signed-by=/usr/share/keyrings/stairwell-archive.gpg] https://downloads.stairwell.com/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/stairwell.list

Install the forwarder

sudo apt update
sudo apt install stairwell

Configure credentials

After install, provide the forwarder with your Stairwell credentials so it can authenticate and begin uploading. Credentials are available in the Stairwell console under Settings → Forwarders.

TODO: Confirm the exact configuration mechanism (config file path, stairwell-forwarder configure command, or environment variables) and fill in before publishing.

Upgrading

Once the repo is configured, upgrades are handled through standard apt tooling:

sudo apt update
sudo apt install --only-upgrade stairwell

Using with configuration management

The repo setup and install steps above can be wrapped in your tool of choice (Ansible, Salt, Chef, Puppet, etc.). In every case the same three things happen:

1. The signing key is placed at /usr/share/keyrings/stairwell-archive.gpg.
2. The repository is registered at /etc/apt/sources.list.d/stairwell.list.
3. The stairwell package is installed via apt.

You are responsible for delivering forwarder credentials to the host through your secrets management system.

Verification

Confirm the package installed and the repository is pinned correctly:

apt-cache policy stairwell

Check that the forwarder service is running:

systemctl status stairwell

TODO: Confirm the actual systemd unit name and replace above if it differs.

Troubleshooting

NO_PUBKEY or signature errors on apt update The keyring file is missing or zero bytes. Re-run the curl … | gpg --dearmor step and verify /usr/share/keyrings/stairwell-archive.gpg exists and is non-empty.

404 Not Found on the repository URL Confirm the host can reach downloads.stairwell.com. Corporate proxies and egress firewalls often block unrecognized domains — allowlist downloads.stairwell.com if needed.

Forwarder installed but not uploading Credentials are not configured or not being read. Check the forwarder log and confirm the configuration file is in place.

TODO: Add forwarder log path once confirmed.