DOCKER.md•5.23 kB
# FastMail MCP Server - Docker Deployment Guide
## Overview
This guide covers deploying the FastMail MCP Server as a Docker container, with specific instructions for Unraid deployment.
## Quick Start
### 1. Local Development
```bash
# Build the container
docker build -t fastmail-mcp-server .
# Run with docker-compose
docker-compose up -d
```
### 2. Environment Setup
Create a `.env` file in the core directory:
```bash
# Required
FASTMAIL_API_TOKEN=your_api_token_here
FASTMAIL_EMAIL=your_email@fastmail.com
# Optional (with defaults)
FASTMAIL_SEND_AS=your_email@fastmail.com
FASTMAIL_ALIAS_DOMAIN=fastmail.com
FASTMAIL_JMAP_URL=https://jmap.fastmail.com/jmap/session
```
## Docker Container Features
- **Base Image**: Node 20 Alpine (~50MB)
- **Security**: Non-root user, read-only filesystem, no new privileges
- **Resources**: 256MB RAM limit, 0.5 CPU limit
- **Health Checks**: Automatic container health monitoring
- **Logging**: JSON structured logs with rotation
- **Signal Handling**: Graceful shutdown on SIGTERM/SIGINT
## Unraid Deployment
### Method 1: Docker Compose Plugin
1. Install the **Compose Manager** plugin from Community Applications
2. Copy your project to `/mnt/user/appdata/fastmail-mcp/`
3. Navigate to **Compose Manager** in Unraid
4. Add the compose file and start
### Method 2: Community Applications Template
1. **Add Template Repository**:
- Go to **Docker** tab in Unraid
- Click **Add Repository**
- URL: `https://github.com/yourusername/fastmail-mcp-server`
2. **Install from Template**:
- Go to **Apps** tab
- Search for "FastMail MCP"
- Click **Install**
- Fill in required fields:
- **FASTMAIL_API_TOKEN**: Your FastMail API token
- **FASTMAIL_EMAIL**: Your email address
3. **Configure Storage**:
- Data path: `/mnt/user/appdata/fastmail-mcp`
- Automatically created on first run
### Method 3: Manual Docker Run
```bash
docker run -d \
--name fastmail-mcp-server \
--restart unless-stopped \
--memory=256m \
--cpus=0.5 \
--read-only \
--tmpfs /tmp \
--tmpfs /var/tmp \
--security-opt no-new-privileges:true \
-v /mnt/user/appdata/fastmail-mcp:/app/data \
-e FASTMAIL_API_TOKEN=your_token \
-e FASTMAIL_EMAIL=your_email@fastmail.com \
fastmail-mcp-server:latest
```
## Claude Code Integration
After deploying the container, update your MCP configuration:
### Option 1: Docker Exec Method
```json
{
"mcpServers": {
"fastmail-server": {
"command": "docker",
"args": ["exec", "-i", "fastmail-mcp-server", "node", "src/index.js"],
"env": {}
}
}
}
```
### Option 2: Socat Bridge (Recommended for Unraid)
Install socat on your Unraid server:
```bash
# Create a script to bridge docker stdio
cat > /mnt/user/appdata/fastmail-mcp/bridge.sh << 'EOF'
#!/bin/bash
docker exec -i fastmail-mcp-server node src/index.js
EOF
chmod +x /mnt/user/appdata/fastmail-mcp/bridge.sh
```
Update your MCP config:
```json
{
"mcpServers": {
"fastmail-server": {
"command": "/mnt/user/appdata/fastmail-mcp/bridge.sh",
"args": []
}
}
}
```
## Building and Publishing
### Build Multi-Architecture Images
```bash
# Enable buildx
docker buildx create --use
# Build for multiple architectures
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag yourdockerhub/fastmail-mcp-server:latest \
--push .
```
### Version Tagging
```bash
# Tag with version
docker tag fastmail-mcp-server:latest yourdockerhub/fastmail-mcp-server:1.0.0
docker push yourdockerhub/fastmail-mcp-server:1.0.0
docker push yourdockerhub/fastmail-mcp-server:latest
```
## Troubleshooting
### Check Container Logs
```bash
# Follow logs
docker logs -f fastmail-mcp-server
# Last 100 lines
docker logs --tail 100 fastmail-mcp-server
```
### Test Container Health
```bash
# Check health status
docker inspect fastmail-mcp-server | grep -A 10 Health
# Manual health check
docker exec fastmail-mcp-server node -e "console.log('Health check')"
```
### Debug MCP Communication
```bash
# Test MCP server directly
docker exec -i fastmail-mcp-server node src/index.js
```
### Common Issues
1. **"Connection closed" error**: Check environment variables are set
2. **Permission denied**: Ensure API token has correct permissions
3. **Container won't start**: Check logs for missing dependencies
4. **High memory usage**: Container is limited to 256MB, should be sufficient
## Security Considerations
- API tokens are masked in Unraid template
- Container runs as non-root user (UID 1001)
- Read-only filesystem prevents tampering
- No network ports exposed (stdio only)
- Automatic security updates via base image updates
## Performance Optimization
- **Memory**: 256MB limit should handle most workloads
- **CPU**: 0.5 CPU limit prevents system overload
- **Storage**: Uses tmpfs for temporary files
- **Logging**: Rotated logs prevent disk filling
## Updates and Maintenance
### Update Container
```bash
# Pull latest image
docker pull yourdockerhub/fastmail-mcp-server:latest
# Recreate container
docker-compose up -d --force-recreate
```
### Monitor Performance
```bash
# Resource usage
docker stats fastmail-mcp-server
# Container info
docker inspect fastmail-mcp-server
```
