Installation and Deployment Guide

Welcome to CXMind Core (Open Source Edition)! This guide will take you through deploying a complete signaling monitoring and analysis system locally or on a server using Docker Compose.

1. Environmental Dependencies

Before starting, please ensure your server or local development environment has the following basic software installed:

• Docker Engine (Version 20.10.0+ or higher)
• Docker Compose (Version v2.0.0+ or higher)
• If using a Linux server, Rocky Linux 9 or Ubuntu 22.04 LTS is recommended.
• Recommended configuration: 2 CPU cores, 4GB RAM, 20GB disk space.

2. Quick Deployment (Docker Compose)

The CXMind Community Edition has packaged all dependent components (Ingestion Engine, Database, Memory Cache, Admin UI) into a pre-configured docker-compose.community.yml. You can pull up the complete system in just two steps:

Step 1: Clone the Source Code Repository

git clone https://github.com/cxmind/cxmind-core.git
cd cxmind-core

Step 2: Start Community Edition Services

Execute the following command, and Docker will automatically pull the required images and start all containers:

docker-compose -f docker-compose.community.yml up -d

The startup process usually takes 1~2 minutes (Initial startup requires downloading images and initializing the database structure). Please be patient.

Step 3: Verify Running Status

Check if all containers are in the Up status using the following command:

docker-compose -f docker-compose.community.yml ps

If everything is normal, you should see critical services running, including ie (Ingestion Engine), admin-ui (Admin UI), surrealdb, and redis.

3. Accessing the Admin UI

After the services start successfully, you can access the local admin console interface using a modern browser:

• Access Address: http://localhost:5173 (If deployed on a cloud server, replace localhost with the server's public IP)
• Default Account: admin@cxmi.ai
• Default Password: admin123

Security Tip: It is strongly recommended to change your administrator password in the system settings after your first login.

4. Verify Data Ingestion via Simulator

To facilitate developers new to communication protocols to quickly experience it, we have built-in a PCAP signaling simulator. You can generate simulated call flows without a physical PBX:

# Execute in the cxmind-core root directory
cd simulator
npm install
npm start

At this point, the simulator will throw SIP/RTCP signaling flows locally, and you can instantly see active call cards emerging in real-time on the monitoring dashboard of the Admin UI.

5. Advanced Deployment: Module Installation by Topology

When deploying CXMind in distributed environments using advanced Sniffer-Go topologies, you will need to install different components on different machines.

5.1 Simple Mode (Single Server)

All components reside on the same server.

• Server: SIP PBX, RTPEngine, CXMind Core (IE, AS, AU, DB, Redis), Sniffer-Go.

5.2 Relay Mode (Separated SIP and RTP)

SIP signaling and RTP media are handled by separate servers.

• SIP Server(s): SIP PBX, Sniffer-Go (configured to forward HEP to the RTP Server's Sniffer-Go).
• RTP Server(s): RTPEngine, Sniffer-Go (configured in Relay Mode relay_upstream: true).
• Central Server: CXMind Core (IE, AS, AU, DB, Redis).

5.3 Peer Mesh Mode (HA Clusters)

Multiple servers handle both SIP and RTP, with potential cross-server media routing.

• Cluster Nodes (A, B, C...): SIP PBX, RTPEngine, Sniffer-Go (configured with hep_peers).
• Central Server: CXMind Core (IE, AS, AU, DB, Redis).

For detailed config.yaml examples for these topologies, please refer to the private enterprise runbook: docs/runbooks/sniffer-go-deployment-topologies.md.

6. Common Troubleshooting

If you encounter startup problems, please check:

1. Port Conflicts: Ensure that local ports 5173 (Frontend), 6379 (Redis), and signaling listening ports UDP 5060 and 9060 are not occupied.
2. Check Logs: Use docker-compose -f docker-compose.community.yml logs -f ie to view the runtime logs of the core Ingestion Engine in real-time to determine if any specific configuration items are missing.

---

If you wish to unlock AI Emotion Recognition, High-Concurrency Media Recording Analysis, and RTP Voice Capture features after your experience, please visit cxmi.ai to apply for a Pro commercial license.