Skip to main content

Deployment

The Master of VALAWAI (MOV) is designed for deployment using Docker containers. Docker is a popular platform for software containerization, allowing applications to run in a self-contained environment with all their dependencies. This simplifies deployment and ensures consistency across different computing environments.

Prerequisites​

Before deploying MOV, ensure you have Docker installed on your system. Installation instructions and platform-specific guides are available on the official Docker website: https://www.docker.com/.

Deployment Steps​

  1. Open a terminal: After installing Docker, open a terminal session. The following deployment procedures will be executed via the command-line interface.

  2. Execute the following commands in your terminal:

#!/bin/bash

# Retrieve the latest stable MOV release
docker run -ti --rm -v ${HOME}:/root -v $(pwd):/git alpine/git clone https://github.com/VALAWAI/MOV.git

# Navigate to the MOV directory
cd MOV

# Launch the MOV (and build the Docker container if needed)
./runMOV.sh
  • In the line 4 this command retrieves the most recent stable release of the Master of VALAWAI.
  • In the line 7 it is the command to go to the dowloaded directory.
  • In the line 10 it is the command to execute the deployment script. This script handles the building the MOV Docker image, and starting the necessary dependencies.
  1. Access MOV: Upon successful completion, the MOV user interface can be accessed via a web browser at: http://localhost:8080 (see the web user interface documentation for further details).

Services deployed​

The deployment script automatically starts the following services:

  • RabbitMQ: The message broker used for inter-component communication within MOV.
  • MongoDB: The persistent data store used by MOV for managing information about components, connections, and logs.

Stopping MOV​

To stop the MOV deployment and its associated services (RabbitMQ and MongoDB), execute the following script:

./stopMOV.sh

This script should be located in the same directory as the runMOV.sh script.

Building the Docker Image​

The recommended way to create a Docker image for the Master Of VALAWAI (MOV) is to run the script:

./buildDockerImages.sh

This script will build the image and tag it with the component's version (e.g., valawai/mov:1.4.0).

The script offers several options for customization:

  • Specify tag: Use -t <tag> or --tag <tag> to assign a custom tag name to the image (e.g., ./buildDockerImages.sh -t my-custom-image-name).
  • Help message: Use -h or --help to display a detailed explanation of all available options.

For example, to build an image with the tag latest, run:

./buildDockerImages.sh -t latest

This will create the container named valawai/mov:latest.

Environment Variables​

Environment variables allow you to configure the MOV application's runtime behavior within the Docker container without rebuilding the image. This section describes the available environment variables:

RabbitMQ Configuration​

  • RABBITMQ_HOST (Default: mov-mq): The hostname or IP address where the RabbitMQ service is listening.
  • RABBITMQ_PORT (Default: 5672): The port on which the RabbitMQ service is listening.
  • RABBITMQ_USERNAME (Default: mov): The username for RabbitMQ authentication.
  • RABBITMQ_PASSWORD (Default: password): CRITICAL: Change this default password immediately for security reasons.

MongoDB Configuration​

  • QUARKUS_MONGODB_HOSTS (Default: mongo:27017): The hostname(s) or connection string for the MongoDB server.
  • QUARKUS_MONGODB_DATABASE (Default: movDB): The name of the MongoDB database used by the application.
  • QUARKUS_MONGODB_CREDENTIALS_USERNAME (Default: mov): The username for MongoDB authentication.
  • QUARKUS_MONGODB_CREDENTIALS_PASSWORD (Default: password): CRITICAL: Change this default password immediately for security reasons.

Other Configuration​

  • MOV_URL (Default: http://localhost:8080): The URL where the MOV user interface will be accessible.

Security Best Practices:​

  • If an environment variable is not set, the application will use its default value.

  • For production deployments, never store passwords directly in environment variables, Dockerfiles, or scripts. Use Docker secrets, a dedicated secrets management service (e.g., HashiCorp Vault), or other secure configuration mechanisms to manage sensitive information.

Use with docker compose​

When you deploy the Master Of VALAWAI (MOV) inside a Docker Compose environment, you can use the provided health check REST endpoints to determine when MOV is ready. These endpoints are:

  • /q/health/live: Checks if the component is running.
  • /q/health/ready: Checks if the component can process messages from the VALAWAI infrastructure.
  • /q/health/started: Checks if the component has started.
  • /q/health: Retrieves all the previous check procedures in the component.

All of them will return a JSON object with the status (either UP or DOWN) and the list of checks that have been evaluated. The /q/health endpoint provides a comprehensive overview. You can also view the health status using the health user interface at /q/health-ui/.

These endpoints are useful for Docker Compose health checks, as shown in the following example:

services:
  mov:
    image: valawai/mov:${MOV_TAG:-latest}
    container_name: mov_ui
    restart: unless-stopped
    depends_on:
      mongo:
        condition: service_healthy
        restart: true
        required: false
      mq:
        condition: service_healthy
        restart: true
        required: false
    ports:
      - ${MOV_UI_PORT:-8080}:8080
    networks:
      - mov_net
    environment:
      RABBITMQ_HOST: mq
      RABBITMQ_PORT: ${MQ_PORT:-5672}
      RABBITMQ_USERNAME: ${MQ_USER:-mov}
      RABBITMQ_PASSWORD: ${MQ_PASSWORD:-password}
      QUARKUS_MONGODB_DATABASE: ${DB_NAME:-movDB}
      QUARKUS_MONGODB_CREDENTIALS_USERNAME: ${DB_USER_NAME:-mov}
      QUARKUS_MONGODB_CREDENTIALS_PASSWORD: ${DB_USER_PASSWORD:-password}
      QUARKUS_MONGODB_HOSTS: ${DB_HOST:-mongo}:${MONGO_PORT:-27017}
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "curl -s http://localhost:8080/q/health | grep -m 1 -P \"^[\\s|\\{|\\\"]+status[\\s|\\:|\\\"]+.+\\\"\" |grep -q \"\\\"UP\\\"\"",
        ]
      interval: 1m
      timeout: 10s
      retries: 5
      start_period: 1m
      start_interval: 5s

networks:
  mov_net:

This Docker Compose file defines the MOV service with dependencies on RabbitMQ and MongoDB. The healthcheck section uses curl to check the /q/health endpoint. Adjust the interval, timeout, retries, and start_period parameters as needed for your specific environment.
These parameters control how frequently the health check is performed, how long it's allowed to take, how many times it's retried before considering the service unhealthy, and how long the service is allowed to start before health checks begin, respectively.

This example also demonstrates how to specify dependencies between services using depends_on. This ensures that RabbitMQ and MongoDB are running before MOV starts.

For a more comprehensive example, including environment variables, volumes, and network configurations, refer to the docker-compose.yml file in the VALAWAI/MOV GitHub repository. This more detailed configuration provides a robust foundation for production deployments.