Chapter 3

Installation

Quick Start — Docker

Four commands: pull the image, start Neo4j, start MeshOptixIQ with your license key, then hit /health. Full stack with TLS? See Chapter 10 — Advanced Deployment for the production Docker Compose file.

3.1 Docker Installation (Recommended)

The official Docker image bundles the FastAPI query API, the React web UI, and the Cython-compiled licensing module. It is the fastest path to a working deployment.

Step 1 — Pull the Image

docker pull meshoptixiq/meshoptixiq:latest

Step 2 — Start Neo4j

docker run -d \
  --name neo4j \
  -p 7687:7687 -p 7474:7474 \
  -e NEO4J_AUTH=neo4j/your-password \
  -v neo4j-data:/data \
  neo4j:5-community

Step 3 — Start MeshOptixIQ

docker run -d \
  --name meshoptixiq \
  -p 8000:8000 \
  --link neo4j:neo4j \
  -e GRAPH_BACKEND=neo4j \
  -e NEO4J_URI=bolt://neo4j:7687 \
  -e NEO4J_USER=neo4j \
  -e NEO4J_PASSWORD=your-password \
  -e MESHOPTIXIQ_LICENSE_KEY=mq-prod-xxxxxxxxxx \
  -e API_KEY=your-api-key-here \
  -v meshoptixiq-cache:/app/cache \
  meshoptixiq/meshoptixiq:latest

Step 4 — Verify

curl http://localhost:8000/health
# {"status":"ok"}

curl http://localhost:8000/health/ready
# {"status":"ok","backend":"neo4j"}

Docker Compose

For production deployments with a complete stack including Neo4j, a reverse proxy, and automatic restarts, see Chapter 10 — Advanced Deployment.

3.2 Python Package Installation

Install directly from PyPI for environments where Docker is not available or for development use.

Base Installation

pip install meshoptixiq-network-discovery

With PostgreSQL Support

pip install "meshoptixiq-network-discovery[postgres]"

With MCP Server

pip install "meshoptixiq-network-discovery[mcp]"

Full Installation (All Extras)

pip install "meshoptixiq-network-discovery[postgres,mcp,integrations]"

Python Version

Python 3.10 or later is required. Python 3.12 is recommended for best performance. Virtual environments (python -m venv .venv) are strongly recommended.

Verify CLI Installation

meshq version
# MeshOptixIQ Network Discovery v0.9.0
# License: Pro (Expires: 2027-12-31)

3.3 License Activation

MeshOptixIQ requires a valid license key for all operations beyond basic collection. Keys are issued at meshoptixiq.com/pricing and take the form mq-prod-xxxxxxxxxx.

Method A — Environment Variable (Recommended for Docker)

export MESHOPTIXIQ_LICENSE_KEY="mq-prod-xxxxxxxxxx"

Pass this to Docker with -e MESHOPTIXIQ_LICENSE_KEY or include it in a .env file with Docker Compose.

Method B — License File (Recommended for Bare-Metal)

mkdir -p ~/.meshoptixiq
echo "mq-prod-xxxxxxxxxx" > ~/.meshoptixiq/license.key
chmod 600 ~/.meshoptixiq/license.key

The application checks the file path ~/.meshoptixiq/license.key on startup; the environment variable takes precedence if both are present.

Security Warning

Never commit license keys to version control. Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, Docker Secrets) for production deployments.

Device Registration

On first startup, MeshOptixIQ registers the host device fingerprint (based on hostname, MAC address, and CPU architecture) with the licensing server. Pro licenses support up to 5 registered devices; Enterprise licenses are unlimited.

3.4 Verifying the Installation

Check the CLI version and license status: meshq version
Verify database connectivity: curl http://localhost:8000/health/ready
List available queries: curl -H "X-API-Key: $API_KEY" http://localhost:8000/queries/
Open the web UI: navigate to http://localhost:8000 in a browser

A successful installation shows 109 queries in the API response and the topology graph in the web UI (empty until data is collected).