DOCKER.md•11.1 kB
# Docker Deployment Guide for MikroTik MCP Server
This guide explains how to deploy and manage the MikroTik MCP Server using Docker and Docker Compose.
## Table of Contents
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Available Services](#available-services)
- [Development Workflow](#development-workflow)
- [Production Deployment](#production-deployment)
- [Networking](#networking)
- [Volumes and Persistence](#volumes-and-persistence)
- [Monitoring and Health Checks](#monitoring-and-health-checks)
- [Backup and Restore](#backup-and-restore)
- [Troubleshooting](#troubleshooting)
- [Advanced Usage](#advanced-usage)
## Prerequisites
- Docker Engine 20.10+
- Docker Compose V2
- At least 2GB RAM
- 10GB free disk space
### Installing Docker
**Linux (Ubuntu/Debian):**
```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
```
**macOS:**
```bash
brew install --cask docker
```
**Windows:**
Download Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop)
## Quick Start
### 1. Clone and Setup
```bash
git clone https://github.com/jeff-nasseri/mikrotik-mcp.git
cd mikrotik-mcp
```
### 2. Initialize Environment
```bash
# Copy environment template
cp .env.example .env
# Initialize project structure
./scripts/deploy.sh init
```
### 3. Configure Your Setup
Edit `.env` file with your MikroTik device details:
```bash
# Edit configuration
nano .env
# Key settings to update:
MIKROTIK_HOST=192.168.1.1
MIKROTIK_USERNAME=admin
MIKROTIK_PASSWORD=your_password
MIKROTIK_PORT=22
```
### 4. Start Services
```bash
# Build and start all services
./scripts/deploy.sh build
./scripts/deploy.sh up
# Or using docker-compose directly
docker-compose up -d
```
### 5. Verify Deployment
```bash
# Check service status
./scripts/deploy.sh status
# View logs
./scripts/deploy.sh logs
# Test connection
docker-compose exec mcp-mikrotik python -c "import mcp_mikrotik; print('MCP Server is running')"
```
## Configuration
### Environment Variables
The `.env` file contains all configuration options:
```bash
# MikroTik Connection
MIKROTIK_HOST=192.168.1.1
MIKROTIK_USERNAME=admin
MIKROTIK_PASSWORD=admin
MIKROTIK_PORT=22
# MCP Server
MCP_PORT=8000
LOG_LEVEL=INFO
# RouterOS Container (for testing)
ROUTEROS_HTTP_PORT=8080
ROUTEROS_SSH_PORT=2222
ROUTEROS_WINBOX_PORT=8291
# Network
NETWORK_SUBNET=172.20.0.0/24
NETWORK_GATEWAY=172.20.0.1
```
### MCP Configuration
Edit `mcp-config.json` for MCP-specific settings:
```json
{
"mcpServers": {
"mikrotik": {
"command": "mcp-server-mikrotik",
"args": [
"--host", "192.168.1.1",
"--username", "admin",
"--password", "admin",
"--port", "22"
]
}
}
}
```
## Available Services
### Core Services
#### mcp-mikrotik
- **Purpose**: Main MCP server for MikroTik integration
- **Port**: 8000 (configurable)
- **Health Check**: Built-in Python health check
- **Dependencies**: None (connects to external MikroTik device)
#### routeros (Optional)
- **Purpose**: RouterOS container for development/testing
- **Ports**:
- Web: 8080 (HTTP), 8443 (HTTPS)
- SSH: 2222
- Winbox: 8291
- API: 8728, 8729 (SSL)
- **Data**: Persistent storage in `routeros-data` volume
### Optional Services
#### mcpo
- **Purpose**: MCP-to-OpenAPI proxy
- **Port**: 9000
- **Use Case**: REST API access to MCP tools
#### traefik
- **Purpose**: Reverse proxy and load balancer
- **Port**: 80 (web), 8081 (dashboard)
- **Profile**: `proxy` (disabled by default)
## Development Workflow
### Development Mode
```bash
# Start in development mode
./scripts/deploy.sh up -e development
# Or with specific profile
COMPOSE_PROFILES=dev docker-compose up -d
# Open development shell
./scripts/deploy.sh shell -s dev
```
### Building and Testing
```bash
# Build images
./scripts/deploy.sh build
# Run tests
./scripts/deploy.sh test
# View logs in real-time
./scripts/deploy.sh logs --follow
```
### Code Changes
For development with live code changes:
```bash
# Mount source code as volume (development profile)
docker-compose --profile dev up -d
# Or edit docker-compose.yml to add bind mounts:
volumes:
- .:/app
- /app/.venv # Exclude virtual environment
```
## Production Deployment
### 1. Security Configuration
```bash
# Generate SSH keys for key-based authentication
ssh-keygen -t rsa -b 4096 -f ./ssh_keys/id_rsa
# Set proper permissions
chmod 600 ./ssh_keys/id_rsa
chmod 644 ./ssh_keys/id_rsa.pub
# Update .env to use key authentication
SSH_PRIVATE_KEY_PATH=./ssh_keys/id_rsa
MIKROTIK_PASSWORD= # Leave empty when using keys
```
### 2. Production Environment
```bash
# Set production environment
echo "DEV_MODE=false" >> .env
echo "DEBUG=false" >> .env
echo "LOG_LEVEL=WARNING" >> .env
# Start production services
./scripts/deploy.sh up -e production
```
### 3. Resource Limits
Add resource limits to `docker-compose.yml`:
```yaml
services:
mcp-mikrotik:
deploy:
resources:
limits:
memory: 512M
cpus: '0.5'
reservations:
memory: 256M
cpus: '0.25'
```
### 4. Monitoring
```bash
# Check health status
./scripts/deploy.sh health
# Monitor resource usage
docker stats
# Set up log rotation
echo "max-size=10m" >> /etc/docker/daemon.json
echo "max-file=3" >> /etc/docker/daemon.json
```
## Networking
### Default Network
- **Subnet**: 172.20.0.0/24
- **Gateway**: 172.20.0.1
- **RouterOS IP**: 172.20.0.2
### Custom Network Configuration
```yaml
# docker-compose.override.yml
networks:
mikrotik-network:
driver: bridge
ipam:
config:
- subnet: 10.0.100.0/24
gateway: 10.0.100.1
```
### External Network Access
```bash
# Connect to existing network
docker network connect existing_network mcp-mikrotik-server
# Or in docker-compose.yml:
networks:
default:
external: true
name: existing_network
```
## Volumes and Persistence
### Data Persistence
```yaml
volumes:
# RouterOS data
routeros-data:
driver: local
# Application logs
app-logs:
driver: local
# Backup storage
backup-storage:
driver: local
```
### Backup Locations
- **Configuration**: `./mcp-config.json`, `./.env`
- **SSH Keys**: `./ssh_keys/`
- **Logs**: `./logs/`
- **Backups**: `./backups/`
- **RouterOS Data**: Docker volume `routeros-data`
## Monitoring and Health Checks
### Built-in Health Checks
```bash
# Check container health
docker-compose ps
# Detailed health status
./scripts/deploy.sh health
# Service-specific health check
docker-compose exec mcp-mikrotik python -c "import mcp_mikrotik; print('Healthy')"
```
### Log Monitoring
```bash
# Real-time logs
./scripts/deploy.sh logs --follow
# Service-specific logs
./scripts/deploy.sh logs -s mcp-mikrotik
# Error logs only
docker-compose logs mcp-mikrotik 2>&1 | grep -i error
```
### External Monitoring
Integration with monitoring systems:
```yaml
# docker-compose.monitoring.yml
services:
prometheus:
image: prom/prometheus
ports:
- "9090:9090"
volumes:
- ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
grafana:
image: grafana/grafana
ports:
- "3000:3000"
environment:
- GF_SECURITY_ADMIN_PASSWORD=admin
```
## Backup and Restore
### Automated Backups
```bash
# Create backup
./scripts/deploy.sh backup
# Backup with timestamp
docker-compose exec mcp-mikrotik mcp-server-mikrotik backup --name "backup_$(date +%Y%m%d_%H%M%S)"
```
### Manual Backup
```bash
# Backup configuration
tar -czf mikrotik_mcp_config_$(date +%Y%m%d).tar.gz \
.env mcp-config.json ssh_keys/
# Backup volumes
docker run --rm -v routeros-data:/data -v $(pwd):/backup \
alpine tar czf /backup/routeros_data_$(date +%Y%m%d).tar.gz -C /data .
```
### Restore Process
```bash
# Restore from backup
./scripts/deploy.sh restore /path/to/backup.tar.gz
# Or manual restore
./scripts/deploy.sh down
tar -xzf backup.tar.gz
./scripts/deploy.sh up
```
## Troubleshooting
### Common Issues
#### Connection Refused
```bash
# Check if MikroTik device is reachable
ping $MIKROTIK_HOST
# Test SSH connection
ssh -p $MIKROTIK_PORT $MIKROTIK_USERNAME@$MIKROTIK_HOST
# Check container connectivity
docker-compose exec mcp-mikrotik ping $MIKROTIK_HOST
```
#### Container Won't Start
```bash
# Check logs for errors
./scripts/deploy.sh logs -s mcp-mikrotik
# Check system resources
docker system df
docker system prune -f
# Rebuild container
./scripts/deploy.sh down
./scripts/deploy.sh build
./scripts/deploy.sh up
```
#### Permission Issues
```bash
# Fix SSH key permissions
chmod 600 ./ssh_keys/id_rsa
chown $USER:$USER ./ssh_keys/id_rsa
# Fix volume permissions
sudo chown -R $USER:$USER ./logs ./backups
```
### Debug Mode
```bash
# Enable debug logging
echo "DEBUG=true" >> .env
echo "LOG_LEVEL=DEBUG" >> .env
# Restart with debug
./scripts/deploy.sh restart
# Interactive debugging
./scripts/deploy.sh shell -s mcp-mikrotik
```
### Performance Issues
```bash
# Check resource usage
docker stats
# Optimize memory usage
echo "PYTHONDONTWRITEBYTECODE=1" >> .env
echo "PYTHONUNBUFFERED=1" >> .env
# Limit log size
echo "max-size=50m" >> /etc/docker/daemon.json
systemctl restart docker
```
## Advanced Usage
### Custom Build
```dockerfile
# Dockerfile.custom
FROM mcp-mikrotik:latest
# Add custom packages
RUN apt-get update && apt-get install -y \
custom-package
# Add custom configuration
COPY custom-config/ /app/config/
```
### Multi-Stage Deployment
```bash
# Build for different environments
docker build --target development -t mcp-mikrotik:dev .
docker build --target production -t mcp-mikrotik:prod .
# Deploy to different environments
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```
### Integration with CI/CD
```yaml
# .github/workflows/docker.yml
name: Docker Build and Deploy
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Build Docker image
run: |
docker build -t mcp-mikrotik:${{ github.sha }} .
- name: Deploy to staging
run: |
docker-compose -f docker-compose.staging.yml up -d
```
### Scaling
```yaml
# docker-compose.scale.yml
services:
mcp-mikrotik:
deploy:
replicas: 3
depends_on:
- loadbalancer
loadbalancer:
image: nginx:alpine
ports:
- "8000:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
```
## Useful Commands
```bash
# Quick reference commands
# Start everything
./scripts/deploy.sh up
# Stop everything
./scripts/deploy.sh down
# Rebuild and restart
./scripts/deploy.sh update
# View logs
./scripts/deploy.sh logs
# Open shell
./scripts/deploy.sh shell
# Check status
./scripts/deploy.sh status
# Clean up
./scripts/deploy.sh clean
# Create backup
./scripts/deploy.sh backup
# Check health
./scripts/deploy.sh health
```
For more detailed information, see the main [README.md](./README.md) file.