`openmas generate-compose` Command¶

The openmas generate-compose command helps automate the creation of a docker-compose.yml file for running your entire OpenMAS project locally using Docker Compose.

Usage¶

openmas generate-compose [OPTIONS]

Options¶

--output-file TEXT: Name of the output Docker Compose file (default: "docker-compose.yml")
--project-dir PATH: Explicit path to the project directory containing openmas_project.yml. If omitted, searches upwards from the current directory.
--image-name TEXT: Base name for the Docker image to use for agent services (default: derived from project name in openmas_project.yml). Assumes a single image can run any agent via AGENT_NAME env var.
--image-tag TEXT: Tag for the Docker image (default: "latest").
--network-name TEXT: Name for the Docker network (default: "_default").
--env-file PATH: Path to an optional .env file to include in the generated services.

Purpose¶

This command aims to simplify the setup for running a multi-agent system locally with Docker Compose by:

Reading Project Configuration: Parses openmas_project.yml to identify all defined agents.
Defining Services: Creates a Docker Compose service definition for each agent listed in the agents: section.
Setting Agent Name: Automatically sets the crucial AGENT_NAME environment variable for each service, telling the container which agent code to run via openmas run.
Configuring Image: Assumes a single Docker image (specified by --image-name and --image-tag) is built (e.g., using openmas generate-dockerfile or manually) that can run any agent based on the AGENT_NAME variable.
Basic Networking: Sets up a default Docker bridge network and connects all agent services to it.
Injecting Service URLs: Attempts to automatically inject SERVICE_URLS__<AGENT_NAME> environment variables into each service, using the Docker Compose service names and default ports (assuming HTTP on 8000/8001 etc., or reading hints from openmas.deploy.yaml if available). This automatic URL injection might require manual adjustment.
Reading Deployment Hints: Optionally reads agents/<agent_name>/openmas.deploy.yaml for hints like exposed ports or specific environment variables for that agent's service.

Example Usage¶

# In your project root directory
# First, ensure you have a suitable Docker image built, e.g., my-mas-image:latest

# Generate docker-compose.yml using default settings
openmas generate-compose

# Generate with a specific image name and output file
openmas generate-compose --image-name my-company/my-mas-image --image-tag v1.1 --output-file compose.prod.yml

Example `docker-compose.yml` Output¶

Given an openmas_project.yml defining orchestrator and worker agents, the generated output might resemble:

# Indented YAML Code Block
# Generated by openmas generate-compose
version: '3.8'

services:
    orchestrator:
    image: my_mas_project-agent:latest # Default image name derived from project
    container_name: orchestrator
    environment:
        AGENT_NAME: orchestrator # Tells the container to run this agent
        OPENMAS_ENV: local # Default, can be overridden
        # --- Auto-injected Service URLs (Review Carefully!) ---
        SERVICE_URLS__WORKER: http://worker:8000 # Assumes worker runs on port 8000
        # Add other necessary env vars (LOG_LEVEL, API keys, etc.)
    ports:
        - "8000:8000" # Default exposed port, adjust if needed
    networks:
        - my_mas_project_default # Default network name

    worker:
    image: my_mas_project-agent:latest
    container_name: worker
    environment:
        AGENT_NAME: worker
        OPENMAS_ENV: local
        # --- Auto-injected Service URLs (Review Carefully!) ---
        SERVICE_URLS__ORCHESTRATOR: http://orchestrator:8000 # Assumes orchestrator runs on port 8000
    ports:
        - "8001:8000" # Example: worker internally runs on 8000, exposed as 8001 on host
    networks:
        - my_mas_project_default

networks:
    my_mas_project_default: # Default network name derived from project
    driver: bridge

Important Considerations & Manual Adjustments¶

Review Generated File: The generated file is a starting point. Always review and adjust it to match your specific needs.
Image Name: Ensure the image: specified matches the image you have built that contains your project code and the openmas framework.
Service URLs: The automatic SERVICE_URLS__* injection makes assumptions about ports (often defaulting to 8000 or based on simple ordering). Verify these URLs and ports are correct for how your agents are configured to listen internally within their containers (e.g., via COMMUNICATOR_OPTIONS__HTTP_PORT). You may need to manually edit these URLs.
Ports: Adjust the ports: mapping (HOST:CONTAINER) as needed. The CONTAINER port must match the port the agent's communicator listens on inside the container.
Environment Variables: Add any other required environment variables for configuration (e.g., LOG_LEVEL, OPENMAS_ENV, API keys, database connection strings). Consider using .env files with Docker Compose for sensitive data.
Dependencies: Add other services your MAS depends on (e.g., databases, message brokers) to the Compose file.
Volumes: Mount volumes if needed for persistent data or configuration files.

openmas run: Run a single agent locally.
openmas generate-dockerfile: Generate a Dockerfile for containerizing agents.
openmas validate: Validate project configuration.
openmas deps: Manage external package dependencies.

openmas generate-compose Command¶