Skip to content

README.md

Latest commit

 

History

History
310 lines (231 loc) · 6.27 KB

README.md

File metadata and controls

310 lines (231 loc) · 6.27 KB

phpIPAM MCP Server - Deployment

This directory contains everything needed to deploy the phpIPAM MCP Server using Docker.

Quick Start

# Copy environment template
cp .env.example .env

# Edit with your credentials
nano .env

# Start the server
docker-compose up -d

# Check logs
docker-compose logs -f phpipam-mcp-server

# Verify health
curl http://localhost:8081/healthz

Files

  • Dockerfile: Multi-stage Docker build configuration
  • docker-compose.yml: Docker Compose deployment configuration
  • .dockerignore: Files excluded from Docker build
  • .env.example: Environment variables template
  • README.md: This file

Configuration

Environment Variables

Required variables in .env:

# phpIPAM Configuration
PHPIPAM_URL=https://your-phpipam-instance.com
PHPIPAM_APP_ID=your_app_id
PHPIPAM_APP_CODE=your_app_code_token

# Optional Settings
PHPIPAM_VERIFY_SSL=true
PHPIPAM_TIMEOUT=30
LOG_LEVEL=INFO

phpIPAM API Setup

  1. Login to phpIPAM as administrator
  2. Navigate to Administration → phpIPAM settings → API
  3. Click Create API application
  4. Configure:
    • App ID: Choose an identifier (e.g., mcp-server)
    • App permissions: Read/Write as needed
    • App security: SSL with App code token
  5. Save and copy the App Code token

Deployment Options

Option 1: Docker Compose (Recommended)

cd deploy
docker-compose up -d

Benefits:

  • Easy configuration via .env file
  • Automatic restart on failure
  • Health checks included
  • Log management configured

Option 2: Docker Build & Run

# Build image
docker build -t phpipam-mcp-server -f deploy/Dockerfile .

# Run container
docker run -d \
  --name phpipam-mcp \
  -p 8080:8080 \
  -e PHPIPAM_URL="https://your-phpipam.com" \
  -e PHPIPAM_APP_ID="your_app_id" \
  -e PHPIPAM_APP_CODE="your_token" \
  --restart unless-stopped \
  phpipam-mcp-server

Option 3: Production Deployment

For production environments, consider:

# docker-compose.prod.yml
version: '3.8'

services:
  phpipam-mcp-server:
    image: phpipam-mcp-server:1.0.0
    restart: always
    ports:
      - "127.0.0.1:8080:8080"  # Only localhost
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "10"
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Health Checks

Manual Check

curl http://localhost:8081/healthz

Expected response:

{
  "status": "ok",
  "version": "1.0.0"
}

Docker Health Status

docker ps
docker inspect phpipam-mcp-server | grep -A 5 Health

Logs

View Logs

# All logs
docker-compose logs

# Follow logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

# Specific service
docker-compose logs phpipam-mcp-server

Log Levels

Set via LOG_LEVEL environment variable:

  • DEBUG: Detailed debugging information
  • INFO: General informational messages (default)
  • WARNING: Warning messages
  • ERROR: Error messages only

Troubleshooting

Connection Issues

Problem: Cannot connect to phpIPAM API

Solutions:

  • Verify PHPIPAM_URL is correct and accessible
  • Check SSL certificate (try PHPIPAM_VERIFY_SSL=false for testing)
  • Verify firewall rules allow outbound HTTPS
  • Test connectivity: docker exec phpipam-mcp-server curl -v $PHPIPAM_URL

Authentication Failures

Problem: 401 or 403 errors

Solutions:

  • Verify PHPIPAM_APP_CODE is correct
  • Check API app is enabled in phpIPAM
  • Ensure security type is "SSL with App Code token"
  • Verify API app has appropriate permissions

Container Won't Start

Problem: Container exits immediately

Solutions:

  • Check logs: docker-compose logs
  • Verify all required environment variables are set
  • Test configuration: docker-compose config
  • Check Docker daemon status

High Memory Usage

Problem: Container uses too much memory

Solutions:

  • Set resource limits in docker-compose.yml
  • Reduce log level to WARNING or ERROR
  • Check for memory leaks in logs
  • Monitor with: docker stats phpipam-mcp-server

Maintenance

Update Container

# Pull latest image
docker-compose pull

# Recreate container
docker-compose up -d

# Or rebuild from source
docker-compose build
docker-compose up -d

Backup Configuration

# Backup .env file
cp .env .env.backup

# Backup Docker configuration
tar -czf phpipam-mcp-backup.tar.gz .env docker-compose.yml

Stop and Remove

# Stop container
docker-compose stop

# Stop and remove
docker-compose down

# Remove with volumes
docker-compose down -v

Security

Best Practices

  1. Use environment files: Never commit .env to version control
  2. Limit network exposure: Bind to localhost in production
  3. Enable SSL: Always use HTTPS for phpIPAM connections
  4. Rotate credentials: Periodically update API tokens
  5. Monitor logs: Watch for unauthorized access attempts
  6. Update regularly: Keep Docker image up to date
  7. Resource limits: Set CPU and memory limits
  8. Read-only filesystem: Consider mounting volumes as read-only

Production Checklist

  • SSL certificate valid and trusted
  • API credentials secured
  • Firewall rules configured
  • Monitoring and alerting setup
  • Backup strategy defined
  • Log rotation configured
  • Health checks working
  • Resource limits set
  • Documentation updated

Monitoring

Prometheus Metrics (Future)

The server can expose Prometheus metrics:

# Add to docker-compose.yml
environment:
  - ENABLE_METRICS=true
ports:
  - "9090:9090"

Integration with Monitoring Tools

  • Prometheus: Scrape /metrics endpoint
  • Grafana: Create dashboards for API calls, errors, latency
  • ELK Stack: Forward logs to Elasticsearch
  • Docker monitoring: Use cAdvisor or similar

Support