installation.md
1 --- 2 title: Installing Agent Mesh Enterprise 3 sidebar_position: 5 4 --- 5 6 This guide walks you through installing and running Agent Mesh Enterprise using Docker. You will download the enterprise image, load it into Docker, and launch a container configured for either development or production use. 7 8 :::tip 9 All the `docker` commands can also be run using any Docker-compatible tool, such as [Podman](https://podman.io/). 10 ::: 11 12 ## Prerequisites 13 14 Before you begin, ensure you have the following: 15 16 - Docker installed on your system 17 - Access to the [Solace Product Portal](https://products.solace.com/prods/Agent_Mesh/Enterprise/) 18 - An LLM service API key and endpoint (optional—you can configure models through the Agent Mesh UI after starting the application) 19 - For production deployments, Solace broker credentials 20 21 ## Understanding the Installation Process 22 23 The installation process consists of three main steps. First, you download and load the Docker image into your local Docker environment. This makes the Agent Mesh Enterprise software available on your system. Second, you identify the exact image name and tag that Docker assigned during the load process. You need this information to reference the correct image when starting your container. Finally, you run the container with the appropriate configuration for your use case—either development mode with an embedded broker or production mode connected to an external Solace broker. 24 25 ## Step 1: Download and Load the Enterprise Image 26 27 You need to obtain the Agent Mesh Enterprise Docker image from the Solace Product Portal and load it into your Docker environment. 28 29 Download the latest enterprise docker image tarball from the [Solace Product Portal](https://products.solace.com/prods/Agent_Mesh/Enterprise/). 30 31 After downloading the tarball, load the image into Docker. This command extracts the image from the compressed archive and makes it available in your local Docker image repository. 32 33 ```bash 34 docker load -i solace-agent-mesh-enterprise-<tag>.tar.gz 35 ``` 36 37 Ensure you replace `<tag>` with the appropriate version number from your downloaded file. 38 39 ## Step 2: Identify the Image Name 40 41 After loading the image, you need to identify its full name and tag. Docker assigns a repository name and tag to the image during the load process, and you will use this information when running the container. 42 43 Run the following command to list all Docker images on your system: 44 45 ```bash 46 docker images 47 ``` 48 49 The output displays all available images with their repository names, tags, image IDs, creation dates, and sizes. Look for the Agent Mesh Enterprise image in the list. 50 51 Example output: 52 ```bash 53 REPOSITORY TAG IMAGE ID CREATED SIZE 54 868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise 1.0.37-c8890c7f31 2589d25d0917 9 days ago 5.25 GB 55 ``` 56 57 Take note of the complete repository name and tag. You will need this full identifier when starting the container. In the example above, the complete image name is `868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31`. 58 59 The numeric hashes at the beginning and end of the repository name (such as `868978040651` and `c8890c7f31`) vary between versions and builds. Your image will have different hash values. 60 61 ## Step 3: Run the Container 62 63 You can run Agent Mesh Enterprise in two different modes depending on your needs. Development mode uses an embedded Solace broker for quick testing and experimentation, while production mode connects to an external Solace broker for enterprise deployments. 64 65 :::tip 66 You may need to include `--platform linux/amd64` depending on the host machine you're using. 67 ::: 68 69 :::warning[Authorization Required] 70 **Agent Mesh Enterprise uses secure-by-default authorization.** Without explicit authorization configuration, the system will **deny all access** to protect your deployment. 71 72 For production use, you must configure RBAC (Role-Based Access Control) to grant access to users. See the [RBAC Setup Guide](./rbac-setup-guide.md) for details. 73 74 For development/testing only, you can disable authorization by setting `type: none` in your configuration, but this should **never** be used in production. (see example below) 75 ::: 76 77 78 ### Running in Development Mode 79 80 Development mode simplifies getting started by using an embedded Solace broker. This configuration requires fewer parameters and allows you to test Agent Mesh Enterprise without setting up external infrastructure. Use this mode for local development, testing, and evaluation. 81 82 The following command starts a container in development mode. The `-itd` flags run the container in interactive mode with a pseudo-TTY, detached in the background. The `-p 8001:8000` flag maps port 8000 inside the container to port 8001 on your host machine, making the web UI accessible at `http://localhost:8001`. 83 84 ```bash 85 docker run -itd -p 8001:8000 \ 86 -e NAMESPACE="<YOUR_NAMESPACE>" \ 87 -e SOLACE_DEV_MODE="true" \ 88 -e SAM_AUTHORIZATION_CONFIG="/preset/auth/insecure_permissive_auth_config.yaml" \ 89 --name sam-ent-dev \ 90 solace-agent-mesh-enterprise:<tag> 91 ``` 92 93 Replace the placeholder values with your actual configuration: 94 95 - `<YOUR_NAMESPACE>`: A unique identifier for your deployment (such as "sam-dev") 96 - `<tag>`: The image tag you identified in Step 2 97 98 The `SOLACE_DEV_MODE="true"` environment variable tells the container to use the embedded broker instead of connecting to an external one. 99 100 :::tip[Configure Models Through the UI] 101 After starting Solace Agent Mesh, open the web interface at `http://localhost:8001` and configure your AI models from the **Models** page. The platform guides you through the initial model setup on first use. For details, see [Model Configurations](../installing-and-configuring/model_configurations.md). 102 103 Alternatively, you can provide LLM configuration as environment variables at container startup by adding `-e LLM_SERVICE_API_KEY`, `-e LLM_SERVICE_ENDPOINT`, `-e LLM_SERVICE_PLANNING_MODEL_NAME`, and `-e LLM_SERVICE_GENERAL_MODEL_NAME` to the `docker run` command. This is useful for automated or headless deployments. 104 ::: 105 106 <details> 107 <summary>Example: Basic Development Mode (Secure Default - Access Denied)</summary> 108 109 ```bash 110 docker run -itd -p 8001:8000 \ 111 -e NAMESPACE="sam-dev" \ 112 -e SOLACE_DEV_MODE="true" \ 113 --name sam-ent-dev \ 114 868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31 115 ``` 116 117 **Note:** This configuration uses secure defaults and will deny all access. You must configure RBAC or use the following permissive development configuration. After starting Solace Agent Mesh, configure your AI models from the **Models** page in the web interface at `http://localhost:8001`. 118 </details> 119 120 <details> 121 <summary>Example: Development Mode with Permissive Authorization (Development Only)</summary> 122 123 You can use the pre-configured development configuration file provided in the `preset` directory. Run the container with the `SAM_AUTHORIZATION_CONFIG` environment variable pointing to this file to disable authorization checks. 124 125 ```bash 126 docker run -itd -p 8001:8000 \ 127 -e NAMESPACE="sam-dev" \ 128 -e SOLACE_DEV_MODE="true" \ 129 -e SAM_AUTHORIZATION_CONFIG="/preset/auth/insecure_permissive_auth_config.yaml" \ 130 --name sam-ent-dev \ 131 868978040651.dkr.ecr.us-east-1.amazonaws.com/solace-agent-mesh-enterprise:1.0.37-c8890c7f31 132 ``` 133 134 After starting Solace Agent Mesh, configure your AI models from the **Models** page in the web interface at `http://localhost:8001`. 135 136 **⚠️ Warning:** This configuration disables authorization and grants full access. Use only for local development. 137 </details> 138 139 ### Running in Production Mode 140 141 Production mode connects to an external Solace broker, which provides enterprise-grade messaging capabilities including high availability, disaster recovery, and scalability. Use this mode when deploying Agent Mesh Enterprise in production environments. 142 143 The production configuration requires additional environment variables to specify the Solace broker connection details. These credentials allow the container to connect to your Solace Cloud service or on-premises broker. 144 145 ```bash 146 docker run -itd -p 8001:8000 \ 147 -e NAMESPACE="<YOUR_NAMESPACE>" \ 148 -e SOLACE_DEV_MODE="false" \ 149 -e SOLACE_BROKER_URL="<YOUR_BROKER_URL>" \ 150 -e SOLACE_BROKER_VPN="<YOUR_BROKER_VPN>" \ 151 -e SOLACE_BROKER_USERNAME="<YOUR_BROKER_USERNAME>" \ 152 -e SOLACE_BROKER_PASSWORD="<YOUR_BROKER_PASSWORD>" \ 153 --name sam-ent-prod \ 154 solace-agent-mesh-enterprise:<tag> 155 ``` 156 157 After starting Solace Agent Mesh, configure your AI models from the **Models** page in the web interface. You can also provide LLM configuration as environment variables at startup (see the preceding development mode section for details). 158 159 Replace the placeholder values with your actual configuration. You need to provide: 160 161 - `<YOUR_BROKER_URL>`: The secured Web Messaging URI for your Solace broker 162 - `<YOUR_BROKER_VPN>`: The Message VPN name for your Solace service 163 - `<YOUR_BROKER_USERNAME>`: The username for broker authentication 164 - `<YOUR_BROKER_PASSWORD>`: The password for broker authentication 165 166 The `SOLACE_DEV_MODE="false"` environment variable tells the container to connect to the external broker specified by the other SOLACE_BROKER parameters instead of using the embedded broker. 167 168 **Ensure you have set up proper RBAC authorization for production deployments.** For more information, see [RBAC Setup Guide](./rbac-setup-guide.md). 169 170 <details> 171 <summary>How to find your credentials</summary> 172 173 Go to Solace Cloud. 174 175 Cluster manager > Your Service > Connect 176 177 Switch dropdown to View by Language 178 179 Open the connect with Python dropdown 180 181 Click Solace Python (Web Messaging) as the protocol. 182 183 Copy: 184 - Username for SOLACE_BROKER_USERNAME, 185 - Password for SOLACE_BROKER_PASSWORD, 186 - Message VPN for SOLACE_BROKER_VPN 187 - Secured Web Messaging URI for SOLACE_BROKER_URL 188 189  190 191 </details> 192 193 ## Infrastructure Setup: S3 Buckets for OpenAPI Connector Specs 194 195 Some enterprise features require additional infrastructure setup. If you plan to use the OpenAPI Connector feature, you must configure a dedicated S3 bucket for OpenAPI specification files. This is separate from artifact storage and is required for agents to download OpenAPI specs at startup. 196 197 ### When is a connector specs bucket required? 198 - When using the OpenAPI Connector feature for REST API integrations 199 - When deploying via Kubernetes (Helm charts handle this automatically) 200 - When agents must access OpenAPI spec files at startup 201 202 ### Why a separate bucket? 203 - **Public read access**: Agents must download OpenAPI specs without authentication 204 - **Security isolation**: Keeps infrastructure files separate from user artifacts 205 - **No secrets**: Only API schemas, endpoints, and models are stored (never credentials) 206 207 ### Setup Instructions 208 209 1. **Create the connector specs S3 bucket** (public read, authenticated write): 210 ```bash 211 aws s3 mb s3://my-connector-specs-bucket --region us-west-2 212 ``` 213 214 2. **Apply a public read policy**: 215 Save as `connector-specs-policy.json`: 216 ```json 217 { 218 "Version": "2012-10-17", 219 "Statement": [{ 220 "Sid": "PublicReadGetObject", 221 "Effect": "Allow", 222 "Principal": "*", 223 "Action": "s3:GetObject", 224 "Resource": "arn:aws:s3:::my-connector-specs-bucket/*" 225 }] 226 } 227 ``` 228 Apply with: 229 ```bash 230 aws s3api put-bucket-policy \ 231 --bucket my-connector-specs-bucket \ 232 --policy file://connector-specs-policy.json 233 ``` 234 235 3. **IAM permissions for write access** (for the SAM service): 236 - Grant `s3:PutObject`, `s3:DeleteObject`, `s3:ListBucket` to the SAM platform's IAM user/role for this bucket. 237 238 4. **Kubernetes deployments**: Use the `connectorSpecBucketName` value in your Helm chart. 239 240 5. **Standalone deployments**: The platform manages the connector specs bucket; see your deployment guide. 241 242 ### Security Notes 243 - Never store API keys, passwords, or secrets in OpenAPI spec files 244 - Public read is safe for API schemas only 245 - Write access should be restricted to the platform 246 247 ## Accessing the Web UI 248 249 After starting the container in either development or production mode, you can access the Agent Mesh Enterprise web interface through your browser. The UI provides a graphical interface for managing agents, monitoring activity, and configuring your deployment. 250 251 Navigate to `http://localhost:8001` in your web browser. The port number corresponds to the host port you specified in the `-p 8001:8000` flag when running the container. 252 253 ## Troubleshooting and Debugging 254 255 If you encounter issues or need to investigate the behavior of your Agent Mesh Enterprise deployment, you can examine the log files generated by the container. These logs provide detailed information about system operations, errors, and debugging information. 256 257 To view logs, check the `.log` files in your container. For information about changing debug levels and advanced debugging techniques, see [Diagnosing and Resolving Problems](../deploying/debugging).