feat: streamline Docker deployment with registry images and unified env configuration

- Update docker-compose.yml to use pre-built images from GitLab registry
- Replace individual environment variables with unified env_file directive
- Create comprehensive .env.example with detailed instructions and troubleshooting
- Add push-to-registry.sh script for building and pushing images to registry
- Add docker-compose.prod.yml as reference for production deployments
- Update documentation to reflect simplified deployment process

Users can now deploy with just:
  cp .env.example .env
  docker-compose pull
  docker-compose up -d

All 7 MCP server images are available at:
  git.oe74.net/adelorenzo/portainer-mcp/portainer-*:latest

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

.env.example

@@ -1,18 +1,97 @@
-# Portainer MCP Environment Configuration
-# Copy this file to .env and update with your values
+# Portainer MCP Server Suite Environment Configuration
+# =====================================================
+# This file contains all environment variables used by the Portainer MCP servers.
+# Copy this file to .env and update with your actual values.
+#
+# IMPORTANT: Never commit the .env file to version control as it contains sensitive credentials.
 
-# Required - Your Portainer instance URL
+# REQUIRED CONFIGURATION
+# ----------------------
+
+# Your Portainer instance URL (must be accessible from Docker containers)
+# Example: https://portainer.example.com
+# Example: http://192.168.1.100:9000
 PORTAINER_URL=https://your-portainer-instance.com
 
-# Required - Your Portainer API key
-# Generate from Portainer UI: My Account > Access Tokens
-PORTAINER_API_KEY=your-api-key-here
+# Your Portainer API key (also called Access Token)
+# To generate an API key:
+# 1. Log in to your Portainer instance
+# 2. Click on your username in the top right
+# 3. Go to "My account" → "Access tokens"
+# 4. Click "Add access token"
+# 5. Give it a name (e.g., "MCP Servers")
+# 6. Copy the generated token and paste it here
+PORTAINER_API_KEY=ptr_your-api-key-here
 
-# Optional - Set to true if using self-signed certificates
+# OPTIONAL CONFIGURATION
+# ----------------------
+
+# Set to true if using self-signed SSL certificates
+# This disables SSL certificate verification (use with caution)
+# Default: false
 PORTAINER_INSECURE=false
 
-# Optional - HTTP request timeout in seconds
+# HTTP request timeout in seconds
+# Increase this value if you have slow network connections or large operations
+# Default: 30
 HTTP_TIMEOUT=30
 
-# Optional - Maximum number of retry attempts
-MAX_RETRIES=3
+# Maximum number of retry attempts for failed API calls
+# The servers will retry with exponential backoff
+# Default: 3
+MAX_RETRIES=3
+
+# ADVANCED CONFIGURATION (rarely needed)
+# --------------------------------------
+
+# Log level for debugging (DEBUG, INFO, WARNING, ERROR)
+# Default: INFO
+# LOG_LEVEL=INFO
+
+# Enable debug mode for verbose output
+# Default: false
+# DEBUG=false
+
+# DOCKER COMPOSE SPECIFIC
+# -----------------------
+# These variables are used by docker-compose.yml but not by the MCP servers
+
+# Docker registry to pull images from (if using private registry)
+# Default uses the GitLab registry where images are hosted
+# DOCKER_REGISTRY=git.oe74.net/adelorenzo/portainer-mcp
+
+# Image tag to use for all services
+# Default: latest
+# IMAGE_TAG=latest
+
+# NETWORK CONFIGURATION
+# ---------------------
+
+# If your Portainer instance is running in Docker on the same host,
+# you might need to use the Docker bridge network IP or container name
+# Example: http://portainer:9000 (if Portainer container is named 'portainer')
+# Example: http://172.17.0.1:9000 (Docker bridge IP on Linux)
+
+# TROUBLESHOOTING TIPS
+# --------------------
+#
+# 1. Connection refused errors:
+#    - Ensure PORTAINER_URL is accessible from within Docker containers
+#    - Try using the Docker host IP instead of localhost
+#    - Check if Portainer is running and accessible
+#
+# 2. Authentication errors:
+#    - Verify your API key is valid and not expired
+#    - Ensure the API key has the necessary permissions
+#    - Check if your Portainer user has the required role (Administrator/Operator)
+#
+# 3. SSL certificate errors:
+#    - Set PORTAINER_INSECURE=true for self-signed certificates
+#    - Ensure your Portainer instance has valid SSL certificates
+#
+# 4. Timeout errors:
+#    - Increase HTTP_TIMEOUT for slow connections
+#    - Check network connectivity between containers and Portainer
+#
+# 5. To test your configuration:
+#    docker-compose run --rm portainer-core python -c "import os; print('URL:', os.getenv('PORTAINER_URL'))"