Docker Compose Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Overview
The AI Network Operations Platform is a self-hosted AI assistant designed to function as an "AI Network Engineer" for enterprise infrastructure teams. It provides a local-first, secure environment where network engineers can interact with their infrastructure using plain English to perform discovery, troubleshooting, configuration management, and DDI (DNS, DHCP, IP Address Management) tasks.
The platform follows a strict design philosophy: every decision made by the AI is explained and audited, and every change to the network requires a human to approve it before execution. It supports a wide range of vendors and protocols, including Cisco (IOS, IOS-XE, NX-OS), Juniper, Arista, Palo Alto, Fortinet, F5, BlueCat, Infoblox, and cloud providers like AWS and Azure.
Specialized "agents" act as virtual team members that the platform routes your questions to based on the task at hand:
- Discovery Agent: Performs inventory enumeration and identifies what exists in the network.
- Troubleshooting Agent: Diagnoses why a specific fault, such as a routing or BGP issue, is occurring.
- DDI Agent: Manages and audits DNS records and DHCP scopes.
- Master Architect: Acts as the team supervisor, analyzing your request and routing it to the correct specialist.
Sources: README.md:3-8, CLAUDE.md:1-19, backend/app/llm/prompts/init.py:126-170
System Overview
This diagram shows how users interact with the platform and the various external systems it connects to.
Sources: CLAUDE.md:12-25, deploy/docker/README.md:27-33
Architecture
The Docker Compose deployment is the standard method for running the platform on a single server, making it ideal for lab environments or small teams. The platform is composed of seven primary components that work together to provide the AI engineering experience.
Platform Components
| Component | Purpose |
|---|---|
| frontend | The operations console where you chat with the AI and view your network topology and audit logs. |
| api | The central brain that handles communication, security checks, and manages the AI sessions. |
| worker | The background engine that runs discovery jobs, takes config backups, and captures packets without blocking your session. |
| postgres | The main database that stores the system of record, including device inventory, audit logs, and AI memory. |
| neo4j | A living topology map that tracks how every device, interface, subnet, and DNS zone connects to everything else. |
| redis | A high-speed messenger used to coordinate tasks between the API and the background workers. |
| ollama | An optional local engine that runs the AI models entirely on your own hardware for maximum privacy. |
Sources: README.md:14-22, deploy/docker/README.md:14-20, deploy/docker/docker-compose.yml:21-140
Vendor Plugin System
To maintain consistency across different manufacturers, the platform uses a standardized connector for each vendor. No matter whether you are talking to a Cisco router or a BlueCat Address Manager, the platform normalizes the output into a consistent format before the AI agents process the data.
Sources: README.md:24-27, CLAUDE.md:27-29
Deployment Options
The platform offers two primary deployment paths depending on your scale and reliability requirements:
- Docker Compose: Best for single-server setups, labs, or small engineering teams. It is easy to start with a single command but lacks high availability.
- Kubernetes / Helm: Designed for production environments. It supports multi-node clusters and high availability to ensure the platform remains reachable even if a server fails.
Sources: deploy/docker/README.md:5-10, deploy/kubernetes/README.md:3-10
Deployment Comparison
This diagram compares the simple single-server approach of Docker Compose with the multi-node production approach of Kubernetes.
Workflows
Agent Routing
When you send a message, the Master Architect determines which specialist is best suited to help you.
Change Approval Workflow
Every modification to your network infrastructure follows a strict lifecycle. A pre-change configuration backup is always taken automatically before any approved change is executed to ensure a rollback is possible.
- Draft: The AI agent creates a proposed change (e.g., adding a DNS record).
- Pending Approval: The change is held in a queue for a human engineer to review.
- Approved: A second human approves the technical details of the change.
- Executing: The platform connects to the device and applies the change.
- Completed/Rolled Back: The platform verifies the change or reverts to the backup if an error occurs.
Data Model
Topology Data Model
The "living topology map" (Neo4j) understands how different network entities relate to one another.
Sources: CLAUDE.md:46-52, README.md:20-22
Configuration
The Docker Compose deployment is configured using a .env file at the repository root. This file contains critical security credentials and operational settings.
| Variable | Description | Default/Example |
|---|---|---|
NETOPS_SECRET_KEY | Used to sign security tokens; must be a strong random string in production. | dev-secret |
NETOPS_NEO4J_PASSWORD | The password for the topology database (Neo4j); must be at least 8 characters. | neo4j |
NETOPS_ADMIN_PASSWORD | The password for the initial "admin" account created on first run. | admin |
NETOPS_LLM_PROFILE | Controls if the platform uses a local LLM or an external provider. | local |
Sources: deploy/docker/README.md:38-70, README.md:30-34
Initial Setup
To start the platform, you must first prepare your environment file and then use Docker Compose with the required environment file flag.
# 1. Create your environment file from the template
cp .env.example .env
# 2. Start the platform services
# The --env-file flag is required to ensure database passwords reach the containers
docker compose --env-file .env -f deploy/docker/docker-compose.yml up -d
# 3. Apply the database schema (Run this only once)
docker compose --env-file .env -f deploy/docker/docker-compose.yml exec api alembic upgrade head
Sources: deploy/docker/README.md:30-34, README.md:37-38
Conclusion
The Docker Compose deployment provides a robust and self-contained environment for network operations. By containerizing the core API, background workers, and specialized databases like the Neo4j topology map, it enables network teams to deploy a powerful AI assistant that respects enterprise security boundaries and maintains a human-in-the-loop for all infrastructure changes.