Skip to main content
The following guide deploys the Minimus RabbitMQ image together with custom self-signed, locally issued certificates generated with OpenSSL to help you get started. The tutorial is appropriate for local development, internal services, and private clusters.

​
What this guide demonstrates

  • TLS handshake validation
  • Server certificate trust
  • Basic auth and RabbitMQ DB operations
  • Image compatibility

​
Components

  • RabbitMQ image built by Minimus: RabbitMQ configured for TLS on both the AMQP port (5671) and the management API port (15671).
  • certgen.sh script: Dynamic certificate generation shell script that uses OpenSSL.
  • minidebug image: A Minimus dev toolkit that provides a shell, OpenSSL, and other utilities used to generate the certificates.

​
Directory Structure

.
├── certgen.sh             # Certificate generation script
├── create-certs.yml       # Compose file to run certgen container
├── certs/                 # Generated certificates (created by certgen.sh)
│   ├── ca_certificate.pem
│   ├── server_certificate.pem
│   └── server_key.pem
├── rabbitmq.conf          # RabbitMQ config file for TLS
├── enabled_plugins        # Enables the management plugin
└── docker-compose.yml     # Compose file to run RabbitMQ

​
2 TLS listeners for 2 trust models

This setup configures two independent TLS listeners, each with a different trust requirement:
  • AMQP (5671) — This is the protocol port your messaging clients connect to. ssl_options.verify = verify_none means the server presents its certificate for the client to trust, but never asks the client for one back. Hence, no client certificate is required.
  • Management API (15671) — This is used by rabbitmqadmin, curl, and the management UI. management.ssl.verify = verify_peer means the server will validate a client certificate if one is presented, but fail_if_no_peer_cert = false makes presenting one optional.
For local development and testing, server-side trust is sufficient: the CA certificate alone (--cacert / --ssl-ca-cert-file) is all a client needs to establish the TLS connections, so this guide skips generating a client certificate. If you later move this setup toward a multi-tenant or zero-trust environment, you can require client certificates on either listener by switching fail_if_no_peer_cert to true.

​
Deploy RabbitMQ with TLS certificates

​
Step 1: Generate TLS certificates

1

Save script that generates TLS certificates

Save the following script to a file named certgen.sh. The script is used to generate the self-signed CA and server certificates and store them in a certs folder in a Docker volume.
certgen.sh
#!/bin/sh
set -e
cd /certs

cat > openssl.cnf <<EOF
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
CN = rabbitmq

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = rabbitmq
DNS.2 = localhost
IP.1 = 127.0.0.1
IP.2 = 192.168.20.0
IP.3 = 192.168.20.2
IP.4 = 192.168.20.3

[v3_ca]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
basicConstraints = critical, CA:true
keyUsage = critical, keyCertSign, cRLSign
EOF

# Generate CA
openssl genrsa -out ca-key.pem 2048
openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 365 \
  -out ca_certificate.pem \
  -subj "/CN=Test CA" -extensions v3_ca -config openssl.cnf

# Generate server cert
openssl genrsa -out server_key.pem 2048
openssl req -new -key server_key.pem -out server.csr -config openssl.cnf -extensions v3_req
openssl x509 -req -in server.csr -CA ca_certificate.pem -CAkey ca-key.pem -CAcreateserial \
  -out server_certificate.pem -days 365 -sha256 -extfile openssl.cnf -extensions v3_req

chmod 600 *.pem
chown -R 1000:1000 /certs/*.pem
chmod 644 /certs/*.pem
2

Save Docker Compose configuration

Save the following YAML configuration to a file named create-certs.yml. The configuration uses the Minimus minidebug image to generate the certificates with the certgen.sh shell script. Minidebug is a Minimus dev toolkit that provides a shell, OpenSSL, and other utilities.
create-certs.yml
services:
  create_certs:
    image: reg.mini.dev/minidebug:latest
    container_name: rabbit_certs
    volumes:
    - ./certs:/certs
    - ./certgen.sh:/certgen.sh:ro
    entrypoint:
    - /bin/sh
    - /certgen.sh
    network_mode: none
3

Generate certificates

Run the following to generate the certificates:
docker compose -f create-certs.yml up
Congrats! You have just generated the following self-signed certificates:
  • CA certificate (ca_certificate.pem)
  • Server certificate and key (server_certificate.pem, server_key.pem) valid for rabbitmq, localhost, 127.0.0.1, 192.168.20.0, 192.168.20.2, and 192.168.20.3
The setup ensures:
  • Proper SANs for rabbitmq and localhost
  • Server cert with both serverAuth and clientAuth extended key usage
In the next steps, you will mount these certificates into the RabbitMQ container.

​
Step 2: Deploy RabbitMQ server

1

Save the configuration file

Save the configuration to a file named rabbitmq.conf.
rabbitmq.conf
## AMQP TLS listener
listeners.ssl.default = 5671

ssl_options.cacertfile = /certs/ca_certificate.pem
ssl_options.certfile   = /certs/server_certificate.pem
ssl_options.keyfile    = /certs/server_key.pem
ssl_options.verify     = verify_none
ssl_options.fail_if_no_peer_cert = false

## Allow remote login for non-guest users
loopback_users.guest = false

## Management API over HTTPS
management.ssl.port = 15671
management.ssl.cacertfile = /certs/ca_certificate.pem
management.ssl.certfile   = /certs/server_certificate.pem
management.ssl.keyfile    = /certs/server_key.pem
management.ssl.verify     = verify_peer
management.ssl.fail_if_no_peer_cert = false
2

Save the enabled plugins

Save the enabled plugins file.
enabled_plugins
[rabbitmq_management].
3

Save Docker Compose script

Save the following Docker Compose script to a file named docker-compose.yml. This script sets up the RabbitMQ service with a healthcheck, mounts a volume with the certificates, maps ports 15671 and 5671.
docker-compose.yml
services:
  rabbitmq:
    image: reg.mini.dev/rabbitmq:latest-dev
    container_name: rabbitmq-lts
    volumes:
      - ./certs:/certs:ro
      - ./rabbitmq.conf:/etc/rabbitmq/rabbitmq.conf:ro
      - ./enabled_plugins:/etc/rabbitmq/enabled_plugins:ro
    environment:
      RABBITMQ_DEFAULT_USER: testuser
      RABBITMQ_DEFAULT_PASS: testpass
    ports:
      - "5671:5671"     # AMQP over TLS
      - "15671:15671"   # Management UI over TLS
4

Run RabbitMQ

Start the RabbitMQ container:
docker compose -f docker-compose.yml up -d

​
Step 3: Test your RabbitMQ server

We will use rabbitmqadmin, the RabbitMQ CLI, to connect over TLS and run tests. For example, here are a few commands you can try out:
  1. Check db health: 
    docker exec -it rabbitmq-lts rabbitmqctl status
curl -u testuser:testpass https://localhost:15671/api/healthchecks/node \
  --cacert ./certs/ca_certificate.pem
  2. Verify the AMQP TLS listener itself (port 5671) with openssl s_client. This confirms the handshake and certificate the broker presents to actual messaging clients, independent of the management API tested in the next step: 
    echo | openssl s_client -connect localhost:5671 -CAfile ./certs/ca_certificate.pem
    openssl s_client runs on your host machine, not inside the container, so the verify result depends on the OpenSSL build installed there. You may see either Verify return code: 0 (ok) or 19 (self-signed certificate in certificate chain) — both mean the handshake succeeded using the certificate signed by your CA. Messaging client libraries (pika, amqplib, etc.) that trust the CA connect the same way regardless.
  3. Test connectivity using rabbitmqadmin. Note that rabbitmqadmin talks to the management HTTP API, so it connects on port 15671 (the TLS management port), not the AMQP port 5671: 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  list queues
  4. Create a test vhost (for example test_vhost). A vhost is RabbitMQ’s equivalent of a database — a logically separate group of queues, exchanges, and permissions: 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  declare vhost name=test_vhost
  5. List all vhosts. 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  list vhosts
  6. Declare a durable queue named docs in test_vhost (the equivalent of creating a collection): 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  declare queue name=docs durable=true
    Then publish a message to it: 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  publish exchange=amq.default routing_key=docs payload="Welcome to TLS RabbitMQ running on a Minimus image"
  7. Create a user (for example, appuser with read/write/configure permissions on test_vhost), get the user’s permission details, and delete the user: 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  declare user name=appuser password=apppass tags=management

rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  declare permission vhost=test_vhost user=appuser configure=.* write=.* read=.*
  8. Publish a new message to the queue: 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  publish exchange=amq.default routing_key=docs payload="Welcome to TLS RabbitMQ running Minimus image"
  9. Get all messages from the queue: 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  --vhost=test_vhost \
  get queue=docs count=10 ackmode=ack_requeue_false
  10. Delete the vhost: 
    rabbitmqadmin \
  --host=localhost \
  --port=15671 \
  --username=testuser \
  --password=testpass \
  --ssl \
  --ssl-ca-cert-file=./certs/ca_certificate.pem \
  delete vhost name=test_vhost
Last modified on July 2, 2026