Skip to content

RabbitMQ Messaging Infrastructure

Overview

This document describes the RabbitMQ virtual host configuration and initialization setup for the Portugal Odyssey platform.

Virtual Hosts

The platform uses environment-specific virtual hosts for RabbitMQ:

  • portugal_odyssey_qual - Qualification/staging environment
  • portugal_odyssey_prod - Production environment
  • portugal_odyssey_dev - Development environment

Automatic Virtual Host Creation

RabbitMQ automatically creates virtual hosts and sets permissions on startup using the definitions file:

Location: infrastructure/config/rabbitmq/definitions.json

This file is mounted into the RabbitMQ container and loaded automatically when RabbitMQ starts. It includes: - Virtual host definitions - User permissions for each virtual host

Method 2: Initialization Script

An initialization script is also available for manual execution or as a fallback:

Location: infrastructure/scripts/init-rabbitmq-vhosts.sh

This script: - Waits for RabbitMQ to be ready - Creates virtual hosts if they don't exist - Grants permissions to the default admin user

Usage: 

docker exec po-rabbitmq /init-rabbitmq-vhosts.sh

Service Auto-Creation

Services that use RabbitMQ have been updated to automatically create virtual hosts if they don't exist:

Updated Services

  1. notification-service (services/notification-service/src/common/rabbitmq/rabbitmq.service.ts)
  2. Automatically creates virtual host via HTTP Management API if connection fails
  3. Grants permissions to the configured user

  4. Retries connection after creation

  5. review-service (services/review-service/src/message-bus.service.ts)

  6. Same auto-creation logic as notification-service
  7. Handles exchange-based messaging

How It Works

When a service tries to connect to RabbitMQ and receives a connection error: 1. The service detects if the error is related to a missing virtual host 2. It uses the RabbitMQ HTTP Management API to create the virtual host 3. It grants permissions to the configured user 4. It retries the connection

This ensures services can recover from missing virtual hosts without manual intervention.

Manual Virtual Host Creation

If you need to create virtual hosts manually:

# Create virtual host
docker exec po-rabbitmq rabbitmqctl add_vhost portugal_odyssey_qual

# Grant permissions to admin user
docker exec po-rabbitmq rabbitmqctl set_permissions -p portugal_odyssey_qual admin ".*" ".*" ".*"

# List all virtual hosts
docker exec po-rabbitmq rabbitmqctl list_vhosts

Configuration

Docker Compose

The RabbitMQ service in infrastructure/compose/shared.yml is configured with:

  • Definitions File: Mounted at /etc/rabbitmq/definitions.json
  • Init Script: Available at /init-rabbitmq-vhosts.sh for manual execution
  • Environment Variables:
  • RABBITMQ_DEFAULT_USER - Default admin user (default: admin)
  • RABBITMQ_DEFAULT_PASS - Password for admin user
  • RABBITMQ_DEFINITIONS_FILE - Path to definitions file

Service Configuration

Services connect to RabbitMQ using the RABBITMQ_URL environment variable:

amqp://username:password@rabbitmq:5672/virtual_host_name

Example for qualification environment: 

RABBITMQ_URL=amqp://admin:password@rabbitmq:5672/portugal_odyssey_qual

Troubleshooting

Virtual Host Not Found

If you see errors like vhost portugal_odyssey_qual not found:

  1. Check if virtual host exists: 

    docker exec po-rabbitmq rabbitmqctl list_vhosts

  2. Create it manually if missing: 

    docker exec po-rabbitmq /init-rabbitmq-vhosts.sh

  3. Or use the service auto-creation - Services will automatically create missing virtual hosts on connection failure

Permissions Issues

If a service can't publish/consume messages:

  1. Check user permissions: 

    docker exec po-rabbitmq rabbitmqctl list_permissions -p portugal_odyssey_qual

  2. Grant permissions: 

    docker exec po-rabbitmq rabbitmqctl set_permissions -p portugal_odyssey_qual admin ".*" ".*" ".*"

Future Improvements

  • Consider using RabbitMQ's federation or sharding features for multi-region deployments
  • Implement virtual host-level resource limits
  • Add monitoring and alerting for virtual host usage