S3 Backups

HitKeep can write both backups and retention archives to S3-compatible object storage.

Use this guide when you want:

off-host backups
object storage retention instead of local disks
MinIO or R2 in self-hosted environments

What Uses S3

Two separate paths can point at S3-compatible storage:

HITKEEP_BACKUP_PATH for EXPORT DATABASE snapshots
HITKEEP_ARCHIVE_PATH for retention Parquet archives

They share the same S3 credential configuration.

Required Settings

At minimum:

export HITKEEP_BACKUP_PATH=s3://my-bucket/hitkeep/backups
export HITKEEP_S3_REGION=eu-central-1

Static credentials:

export HITKEEP_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export HITKEEP_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Or rely on the AWS credential chain for IAM roles, ECS task roles, or similar.

AWS S3 Example

export HITKEEP_DATA_PATH=/var/lib/hitkeep/data
export HITKEEP_BACKUP_PATH=s3://my-analytics-bucket/hitkeep/backups
export HITKEEP_BACKUP_INTERVAL=60
export HITKEEP_BACKUP_RETENTION=24
export HITKEEP_S3_REGION=eu-central-1

./hitkeep

MinIO Example

export HITKEEP_BACKUP_PATH=s3://hitkeep/backups
export HITKEEP_ARCHIVE_PATH=s3://hitkeep/archive
export HITKEEP_S3_ACCESS_KEY_ID=minioadmin
export HITKEEP_S3_SECRET_ACCESS_KEY=minioadmin
export HITKEEP_S3_ENDPOINT=localhost:9000
export HITKEEP_S3_URL_STYLE=path
export HITKEEP_S3_USE_SSL=false
export HITKEEP_S3_REGION=us-east-1

./hitkeep

Cloudflare R2 Example

export HITKEEP_BACKUP_PATH=s3://my-r2-bucket/hitkeep/backups
export HITKEEP_S3_ACCESS_KEY_ID=YOUR_R2_ACCESS_KEY
export HITKEEP_S3_SECRET_ACCESS_KEY=YOUR_R2_SECRET_KEY
export HITKEEP_S3_ENDPOINT=YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
export HITKEEP_S3_REGION=auto

./hitkeep

Bucket Layout

Built-in backups use this logical layout:

s3://bucket/hitkeep/backups/
  shared/
    2026-03-08T120000Z/
  tenants/
    5c6644da-ef00-45e6-825d-c755d19d7f9f/
      2026-03-08T120000Z/

Retention archives use your configured archive prefix and write Parquet objects there.

Retention on S3

For local backup destinations, HitKeep prunes older snapshots automatically based on HITKEEP_BACKUP_RETENTION.

For S3 destinations, prefer provider-side lifecycle rules:

keep recent snapshots hot
expire old snapshots automatically
move older archives to cheaper storage classes if your provider supports it

That keeps retention behavior transparent and avoids a surprise cost curve in object storage.

Restore From S3

When restoring from S3, provide the exact snapshot timestamp:

./hitkeep recover restore-backup \
  -from s3://my-analytics-bucket/hitkeep/backups \
  -snapshot 2026-03-08T120000Z \
  -s3-region eu-central-1 \
  -yes

Unlike local snapshots, HitKeep does not currently auto-discover “latest” from S3.

Common Mistakes

Using only HITKEEP_ARCHIVE_PATH and assuming backups are enabled
Backing up only the shared DB while teams are enabled
Forgetting HITKEEP_S3_URL_STYLE=path for MinIO-style endpoints
Using HTTP endpoints without HITKEEP_S3_USE_SSL=false
Assuming S3 restore can infer the latest snapshot automatically