Skip to main content

Quickstart

Get a working backup running in under 5 minutes. You will install the tool, start a local RabbitMQ broker, back up a queue, and verify the result.

Prerequisites​

Step 1: Install​

Option A: Build from Source​

git clone https://github.com/osodevops/rabbitmq-backup.git
cd rabbitmq-backup
cargo build --release

The binary is at ./target/release/rabbitmq-backup.

Option B: Download Pre-built Binary​

# Download the latest release (replace with your platform)
curl -LO https://github.com/osodevops/rabbitmq-backup/releases/latest/download/rabbitmq-backup-x86_64-linux
chmod +x rabbitmq-backup-x86_64-linux
mv rabbitmq-backup-x86_64-linux /usr/local/bin/rabbitmq-backup

Verify the installation:

rabbitmq-backup --version

Expected output:

rabbitmq-backup 0.1.0

Step 2: Start Local RabbitMQ​

Use the included Docker Compose file to spin up RabbitMQ with management and stream plugins enabled:

docker compose up -d rabbitmq

Wait for RabbitMQ to be ready (about 10-15 seconds):

# Check that the management API responds
curl -s -u guest:guest http://localhost:15672/api/overview | head -c 100
tip

The Docker Compose file also includes a rabbitmq-setup service that creates sample orders-queue and payments-queue queues. Run docker compose up -d rabbitmq-setup to create them automatically.

Step 3: Create a Queue and Publish Test Messages​

Create a queue and publish a few messages using rabbitmqadmin:

# Create a test queue
docker exec rabbitmq rabbitmqadmin declare queue name=demo-queue durable=true

# Publish some test messages
for i in $(seq 1 10); do
  docker exec rabbitmq rabbitmqadmin publish \
    exchange=amq.default \
    routing_key=demo-queue \
    payload="Message $i: Hello from RabbitMQ backup quickstart"
done

Verify the messages are in the queue:

docker exec rabbitmq rabbitmqadmin list queues name messages

Expected output:

+------------+----------+
|    name    | messages |
+------------+----------+
| demo-queue | 10       |
+------------+----------+

Step 4: Create a Config File​

Create a minimal backup configuration file:

cat > quickstart-backup.yaml << 'EOF'
mode: backup
backup_id: "quickstart-001"

source:
  amqp_url: "amqp://guest:guest@localhost:5672/%2f"
  management_url: "http://localhost:15672"
  management_username: guest
  management_password: guest

  queues:
    include:
      - "demo-queue"
    vhosts:
      - "/"

storage:
  backend: filesystem
  path: ./quickstart-data

backup:
  compression: zstd
  requeue_strategy: cancel
  include_definitions: true
  stop_at_current_depth: true
EOF
info

The requeue_strategy: cancel setting is key to non-destructive backup. The tool starts a consumer, reads messages, then cancels the consumer -- all unacknowledged messages are automatically requeued by RabbitMQ.

Step 5: Run the Backup​

rabbitmq-backup backup --config quickstart-backup.yaml

Expected output:

2026-04-10T12:00:00.000Z  INFO rabbitmq_backup_core::backup: Starting backup quickstart-001
2026-04-10T12:00:00.050Z  INFO rabbitmq_backup_core::backup: Connected to RabbitMQ at localhost:5672
2026-04-10T12:00:00.100Z  INFO rabbitmq_backup_core::definitions: Exporting definitions from http://localhost:15672
2026-04-10T12:00:00.200Z  INFO rabbitmq_backup_core::backup::queue_reader: Backing up queue demo-queue (10 messages)
2026-04-10T12:00:00.350Z  INFO rabbitmq_backup_core::backup::queue_reader: Queue demo-queue complete: 10 messages in 1 segment
2026-04-10T12:00:00.400Z  INFO rabbitmq_backup_core::backup: Backup quickstart-001 complete: 10 messages, 1 queue, 1 segment

Step 6: Verify the Backup​

Check that messages are still in the queue (non-destructive)​

docker exec rabbitmq rabbitmqadmin list queues name messages

Expected output -- the queue depth is unchanged:

+------------+----------+
|    name    | messages |
+------------+----------+
| demo-queue | 10       |
+------------+----------+

List backups in storage​

rabbitmq-backup list --path ./quickstart-data

Expected output:

Available backups:
  quickstart-001    2026-04-10T12:00:00Z    1 queue    10 messages    1 segment

Describe the backup​

rabbitmq-backup describe --path ./quickstart-data --backup-id quickstart-001

Expected output:

Backup: quickstart-001
  Created:      2026-04-10T12:00:00Z
  Status:       complete
  Queues:       1
  Messages:     10
  Segments:     1
  Compression:  zstd
  Definitions:  included

  Queues:
    /demo-queue    10 messages    1 segment    4.2 KB

Validate backup integrity​

rabbitmq-backup validate --path ./quickstart-data --backup-id quickstart-001 --deep

Expected output:

Validating backup quickstart-001...
  Manifest:     OK
  Definitions:  OK
  Segments:     1/1 OK (checksums verified)
  Messages:     10/10 OK

Validation passed.

What's Next?​

You have a working backup. From here:

warning

The quickstart uses filesystem storage and plaintext credentials. For production deployments, see the Security Setup and Cloud Setup guides.