PSS®X package for RabbitMQ¶

What is RabbitMQ?¶

The respective trademarks mentioned in the offering are owned by the respective companies, and use of them does not imply any affiliation or endorsement

Featured tags¶

• 4.0.5-bookworm-slim-amd64
  docker pull registry.gitlab.com/pss-x/support/containers/rabbitmq:4.0.5-bookworm-slim-amd64

About this image¶

This is a non-root container image, which adds an extra layer of security and is generally recommended for production environments. However, because they run as a non-root user, privileged tasks are typically off-limits.

How to use this image¶

You can get started with RabbitMQ

docker run --name pssx-rabbitmq -p 5672:5672 -p 15672:15672 -d registry.gitlab.com/pss-x/support/containers/rabbitmq:<use-featured-tag>

Warning: These quick setups are only intended for development environments. You are encouraged to change the insecure default credentials and check out the available configuration options in the Configuration section for a more secure deployment.

Configuration¶

Requirements¶

• This image requires Docker Engine 1.8+ in any of their supported platforms
• At least 4 GB of RAM.

Environment variables¶

Customizable environment variables¶

Read-only environment variables¶

When you start the rabbitmq image, you can adjust the configuration of the instance by passing one or more environment variables either on the docker-compose file or on the docker run command line. If you want to add a new environment variable:

• For docker-compose add the variable name and value under the application section in the docker-compose.yml file present in this repository: :

rabbitmq:
  ...
  environment:
    - RABBITMQ_PASSWORD=my_password
  ...

• For manual execution add a -e option with each variable and value.

Using a Docker Compose file¶

Using Docker container networking, a RabbitMQ server running inside a container can easily be accessed by your application containers.

Containers attached to the same network can communicate with each other using the container name as the hostname.

services:
  rabbitmq:
    container_name: pssx-rabbitmq
    image: registry.gitlab.com/pss-x/support/containers/rabbitmq:<use-featured-tag>
    ports:
      - 5672:5672
      - 15672:15672
    environment:
      - RABBITMQ_SECURE_PASSWORD=yes # this will be ensure password value will not exposed in the configuration files
      - RABBITMQ_LOGS=-
      - RABBITMQ_USERNAME=user
      - RABBITMQ_PASSWORD=my_password
      - RABBITMQ_MANAGEMENT_ALLOW_WEB_ACCESS=true
    networks:
      - pssx-network

networks:
  pssx-network:
    name: app-pssx-network
    driver: bridge

Persisting your application¶

If you remove the container all your data will be lost, and the next time you run the image the database will be reinitialized. To avoid this loss of data, you should mount a volume that will persist even after the container is removed.

For persistence you should mount a directory at the /bitnami/rabbitmq/mnesia path. If the mounted directory is empty, it will be initialized on the first run.

docker run \
    -v /path/to/rabbitmq-persistence:/bitnami/rabbitmq/mnesia \
    registry.gitlab.com/pss-x/support/containers/rabbitmq:<use-featured-tag>

You can also do this by modifying the docker-compose.yml file present in this repository:

services:
  rabbitmq:
    ...
    volumes:
      - rabbitmq_data:/bitnami/rabbitmq/mnesia
    ...

volumes:
  rabbitmq_data:
    name: pssx_rabbitmqdata
    driver: local

NOTE: As this is a non-root container, the mounted files and directories must have the proper permissions for the UID 1001.

Configuration file¶

A custom rabbitmq.conf configuration file can be mounted to the /bitnami/rabbitmq/conf directory. If no file is mounted, the container will generate a default one based on the environment variables. You can also mount on this directory your own advanced.config (using classic Erlang terms) and rabbitmq-env.conf configuration files.

As an alternative, you can also mount a custom.conf configuration file and mount it to the /bitnami/rabbitmq/conf directory. In this case, the default configuation file will be generated and, later on, the settings available in the custom.conf configuration file will be merged with the default ones. For example, in order to override the listeners.tcp.default directive:

Step 1: Write your custom.conf configuation file with the following content¶

listeners.tcp.default=1337

Step 2: Run RabbitMQ mounting your custom.conf configuation file¶

docker run -d --name rabbitmq-server \
   -v /path/to/custom.conf:/bitnami/rabbitmq/conf/custom.conf:ro \
    registry.gitlab.com/pss-x/support/containers/rabbitmq:<use-featured-tag>

After that, your changes will be taken into account in the server's behaviour.

Handling sensitive information¶

In Docker, environment variables with the _FILE suffix are a convention used to specify that the value of the environment variable should be read from a file.

• Environment Variable with _FILE Suffix: When an environment variable ends with _FILE, it indicates that the actual value of the variable should be read from the file specified by the path.
• Usage in Docker: This approach is commonly used in Docker to securely pass sensitive information to containers without hardcoding the values in the docker-compose.yml file or Dockerfile.

services:
  rabbitmq:
    ...
    environment:
      - RABBITMQ_SECURE_PASSWORD=yes
      - RABBITMQ_LOGS=-
      - RABBITMQ_USERNAME=user
      - RABBITMQ_PASSWORD_FILE=/run/secrets/RABBITMQ_PASSWORD
      - RABBITMQ_MANAGEMENT_ALLOW_WEB_ACCESS=true
    secrets:
      - RABBITMQ_PASSWORD
    ...

secrets:
  RABBITMQ_PASSWORD:
    file: ./etc/secrets/rabbitmq.pwd
    ...

Health checks¶

The healthcheck section in a Docker Compose file allows you to define a command that Docker will run to check the health of a service. This helps ensure that your services are running correctly and can automatically handle failures.

services:
  rabbitmq:
    ...
    healthcheck:
      test: rabbitmq-diagnostics -q ping
      interval: 30s
      timeout: 30s
      retries: 3
    ...

SSL (Secure Sockets Layer) Configuration¶

The RabbitMQ has inbuilt support for TLS. This includes client connections and popular plugins, where applicable. The ports 5671 and 15671 are used for SSL communication for RabbitMQ and its management plugin, respectively.

Here are the relevant environment variables and their meanings:

• RABBITMQ_NODE_SSL_PORT_NUMBER: RabbitMQ node port number for SSL connections.
  Defaults to 5671.
• RABBITMQ_SSL_CACERTFILE: Specifies the path to the CA (Certificate Authority) certificate file.
  This certificate is used to verify the server's certificate.
  No defaults.
• RABBITMQ_SSL_CERTFILE: Specifies the path to the server's certificate file.
  This certificate is presented to clients during the SSL handshake.
  No defaults.
• RABBITMQ_SSL_KEYFILE: Specifies the path to the server's private key file.
  This key is used in conjunction with the server's certificate. No defaults.
• RABBITMQ_SSL_FAIL_IF_NO_PEER_CERT: Controls whether the server fails the SSL handshake if the client does not present a certificate.
  Defaults to no.
• RABBITMQ_SSL_VERIFY: Controls whether the server verifies the client's certificate.
  Defaults to verify_none.

The RabbitMQ Management Plugin is also configured to use SSL for secure communication. The relevant environment variables are similar to those for the RabbitMQ service:

• RABBITMQ_MANAGEMENT_SSL_PORT_NUMBER: RabbitMQ management server port number for SSL/TLS connections.
  Defaults to 15671
• RABBITMQ_MANAGEMENT_SSL_CACERTFILE: Specifies the path to the CA certificate file for the management plugin.
  Defaults to $RABBITMQ_SSL_CACERTFILE
• RABBITMQ_MANAGEMENT_SSL_CERTFILE: Specifies the path to the server's certificate file for the management plugin.
  Defaults to $RABBITMQ_SSL_CERTFILE
• RABBITMQ_MANAGEMENT_SSL_KEYFILE: Specifies the path to the server's private key file for the management plugin.
  Defaults to $RABBITMQ_SSL_KEYFILE
• RABBITMQ_MANAGEMENT_SSL_FAIL_IF_NO_PEER_CERT: Controls whether the management plugin fails the SSL handshake if the client does not present a certificate.
  Defaults to yes
• RABBITMQ_MANAGEMENT_SSL_VERIFY: Controls whether the management plugin verifies the client's certificate.
  Defaults to verify_peer

services:
  rabbitmq:
    ...
    ports:
      - 5671:5671
      - 5672:5672
      - 15671:15671
      - 15672:15672
      - 25672:25672
    environment:
      - RABBITMQ_SSL_CACERTFILE=/opt/bitnami/rabbitmq/certs/myOrganizationRootCA.pem
      - RABBITMQ_SSL_CERTFILE=/opt/bitnami/rabbitmq/certs/myOrganizationCert.pem
      - RABBITMQ_SSL_KEYFILE=/opt/bitnami/rabbitmq/certs/myOrganizationCertKey.pem
      - RABBITMQ_SSL_VERIFY=verify_peer
      - RABBITMQ_SSL_FAIL_IF_NO_PEER_CERT=yes
      - RABBITMQ_MANAGEMENT_SSL_FAIL_IF_NO_PEER_CERT=yes
      - RABBITMQ_MANAGEMENT_SSL_VERIFY=verify_peer
      - RABBITMQ_SECURE_PASSWORD=no
    volumes:
      - ./etc/certs:/opt/bitnami/rabbitmq/certs
    ...
    healthcheck:
      test: rabbitmq-diagnostics -q ping
      interval: 30s
      timeout: 30s
      retries: 3
    ...

Note that mkcert and the certificate/key pairs it generates are self-signed and only suitable for development and test environments. The vast majority of production environments should use certificates and keys issued by a widely trusted commercial CA.

services:
  rabbitmq:
    ...
    ports:
      - 5671:5671
      - 5672:5672
      - 15671:15671
      - 15672:15672
      - 25672:25672
    environment:
      - RABBITMQ_SSL_CACERTFILE=/opt/bitnami/rabbitmq/certs/rootCA.pem
      - RABBITMQ_SSL_CERTFILE=/opt/bitnami/rabbitmq/certs/cert.pem
      - RABBITMQ_SSL_KEYFILE=/opt/bitnami/rabbitmq/certs/key.pem
      # Setting it to verify_none means the server will not verify the client's certificate.
      - RABBITMQ_SSL_VERIFY=verify_none
      # Setting it to no means the server will not fail the handshake if the client does not present a certificate.
      - RABBITMQ_SSL_FAIL_IF_NO_PEER_CERT=no
      - RABBITMQ_MANAGEMENT_SSL_FAIL_IF_NO_PEER_CERT=no
      - RABBITMQ_MANAGEMENT_SSL_VERIFY=verify_none
      - RABBITMQ_SECURE_PASSWORD=no
    volumes:
      - ./etc/certs:/opt/bitnami/rabbitmq/certs
    ...
    healthcheck:
      # Tell curl to not verify the peer
      test: ["CMD", "curl", "-s", "-k", "-f", "https://localhost:15671"]
      interval: 30s
      timeout: 30s
      retries: 3
    ...

Permission of SSL/TLS certificate and key files¶

If you bind mount the certificate and key files from your local host to the container, make sure to set proper ownership and permissions of those files:

sudo chown 1001:root <your cert/key files>
sudo chmod 400 <your cert/key files>

License¶

View license information for the software contained in this image.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

Some additional license information which was able to be auto-detected might be found in the repo-info repository's rabbitmq/ directory.

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.