Introduction

thumper is a self-contained tool for deploying static assets to BunnyCDN storage zones. It is straightforward to integrate into CI/CD and deploys static web pages quickly.

Features

• Syncs only files that have changed locally
• Delete files remotely that are missing locally
• Concurrency control to prevent concurrent deploys
• Concurrent file discovery and upload for quick deployments
• Syncs html files last
• Dry runs and verbose output
• Auto-complete

Getting thumper

The recommended method of installing is to use mise:

mise use ubi:kaaveland/thumper@latest

This downloads the latest release for your platform from the releases page, which you can also do manually.

There's a docker image available at ghcr.

It is also possible to install thumper with cargo install thumper.

The code is available under the MIT License and the repository is at GitHub.

Usage

thumper needs to authenticate to BunnyCDN in order to work. The recommended approach is to make two environment variables available:

• THUMPER_KEY - this is the password to a BunnyCDN storage zone.
• THUMPER_API_KEY - this is the api key to BunnyCDN. It is only necessary if you want thumper to purge your pull zone.

Make sure to keep these values secret, an attacker could do a lot of damage with them.

thumper

Sync your files to bunny cdn storage zone

Usage: thumper <COMMAND>

Commands:
  sync         Sync a local folder to a path within a bunny.net Storage Zone
  completions  Provide shell completions
  purge-url    Purge a URL from the bunny.net cache
  purge-zone   Purge an entire pull zone from bunny.net cache
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help (see more with '--help')
  -V, --version  Print version

thumper sync

Sync a local folder to a path within a bunny.net Storage Zone

Usage: thumper sync [OPTIONS] <local_path> <storage_zone>

Arguments:
  <local_path>    Local directory to put in the storage zone
  <storage_zone>  Which storage zone to sync to

Options:
  -e, --endpoint <ENDPOINT>        Which bunny cdn endpoint to use [default: storage.bunnycdn.com]
  -a, --access-key <ACCESS_KEY>    Password for the storage zone - looked up in environment variable THUMPER_KEY if not present
  -p, --path <PATH>                Path inside the storage zone to sync to, path to a directory [default: /]
      --dry-run                    Don't sync, just show what would change
  -f, --force                      Force a sync despite a hanging lock file
      --lockfile <LOCKFILE>        Filename to use for the lockfile. thumper will not sync if this file exists in the destination [default: .thumper.lock]
  -i, --ignore <IGNORE>            Do not delete anything in the storage zone paths that start with this prefix (can pass multiple times)
  -v, --verbose                    
  -c, --concurrency <CONCURRENCY>  Number of threads to use when calling bunny.net API (default to number of cpus)
  -h, --help                       Print help

Deploying a static site with GitHub Actions

Setting up BunnyCDN storage zone

From the Storage page at BunnyCDN, click Add Storage Zone. Give your storage zone a memorable name and choose a tier and main storage region. If you choose a different region than "Europe (Falkenstein)", you will need to provide --endpoint to thumper sync later. Set up your desired amount of Geo Replication and click "Add Storage Zone."

Now you should have an empty Storage Zone. Navigate to the "FTP & API Access" pane. The Hostname that is listed corresponds to the --endpoint parameter to thumper sync. The password corresponds to the THUMPER_KEY environment variable or --access-key command line parameter. Put it somewhere safe, like a GitHub Actions secret, available under https://github.com/YOURNAME/YOURPROJECT/settings/secrets/actions.

Optionally, if you want to purge the cache when you deploy a new version of your site, you will need your BunnyCDN API key. You will find it under your profile page. Create a secret for that too. This is THUMPER_API_KEY. This makes for 2 secrets:

• THUMPER_KEY is the password for your storage zone.
• THUMPER_API_KEY is the bunny.net API key for your account.

Setting up a GitHub Workflow

This documentation site is deployed to a BunnyCDN storage site with a GitHub workflow. The workflow looks like this:

name: Deploy documentation

on:
  push:
    tags:
      - '*.*.*'
  workflow_dispatch: {}

jobs:
  deploy_docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: jdx/mise-action@v2
    - name: Render CLI help
      run: cargo test
    - name: Render mdbook
      run: mdbook build docs
    - name: Deploy docs to kaveland/thumper
      run: thumper sync docs/book kaveland --path thumper --concurrency 4 --verbose
      env:
        THUMPER_KEY: ${{ secrets.THUMPER_KEY }}
    - name: Purge pull zone
      run: thumper purge-zone 3644443
      env:
        THUMPER_API_KEY: ${{ secrets.THUMPER_API_KEY }}

The first few steps in the deploy_docs job are all about producing the static site files. The repository is cloned. Then we use jdx/mise-action to install mdbook which builds the static site, and thumper from mise.toml at the root of the repository:

[tools]

"ubi:rust-lang/mdbook" = "v0.4.48"
"ubi:kaaveland/thumper" = "latest"

The thumper sync command uses --path thumper to place the static site at thumper/ in the storage zone. This is not necessary if you want to sync your site to the root of the storage zone instead, but this documentation site shares the domain with a few others. You may have to provide --endpoint to thumper sync.

Purging the cache with thumper purge-zone is optional. This command takes the ID of your pull zone as an argument—it is the numeric part of the URL to the pull zone page. You can force a cache-refresh immediately with this approach, making your new content available faster. This enables you to set a very high Cache Expiration Time. You can also use thumper purge-url with a * wildcard at the end of your URL, to purge only parts of your page.

Setting up a BunnyCDN Pull Zone

Once you've verified that you can sync to your storage zone, you can configure a BunnyCDN pull zone to make your content available to the world. Here's the official guide.

Why?

Why BunnyCDN?

I like BunnyCDN because:

• It is very affordable.
• It is a European provider in a space dominated by American big tech.
• Geo-replicated Storage Zones have amazing performance globally.
• BunnyDNS has amazing performance globally.
• It is straightforward to configure.
• I have access to basic reporting on page hits.

I have an affiliate link that you could use if you want to make an account.

Why thumper?

I wanted a checksum-based sync tool that was convenient for both CI/CD and local use. It was important to me to have a fast installation to support CI usage. I wanted a fully self-contained binary that I could just plonk into a ~/bin folder on any of my machines.

Thumper is the name of a very famous bunny.