HitKeep S3 Backups and Object Storage

Esta página aún no está disponible en tu idioma.

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.

Which path should use S3?

Use S3 for backups when the server disk is not enough protection. Use S3 for archives when retention rules move older analytics rows out of the live DuckDB files.

Need	Set this	Result
Off-host snapshots	`HITKEEP_BACKUP_PATH=s3://...`	Built-in backup snapshots are written to object storage
Long-term Parquet archives	`HITKEEP_ARCHIVE_PATH=s3://...`	Retention archives are written to object storage
Both	Set both paths	Backups and archives share S3 credentials but use separate prefixes

Keep backup prefixes and archive prefixes separate. Backups are restore points. Archives are reporting/history files created by retention policy.

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