Skip to main content
The connector is a critical component that enables ModMS to query data from remote archive servers.

​
Purpose

The connector service allows:
  • Remote data access: Main ModMS server can query data stored on archive servers
  • Distributed queries: Queries are automatically routed to the appropriate server based on registry.json
  • Transparent access: Clients query the main server, which handles routing to archive servers

​
How It Works

  1. Main Server: Runs both modms (API) and connector services
  2. Archive Servers: Run only connector services
  3. Registry: The main server’s registry.json defines which models are on which servers
  4. Query Routing: When a query comes in, the main server checks the registry and routes the query to the appropriate connector

​
Configuration

​
Environment Variables

  • CONNECTOR_PORT: Port the connector listens on (default: 8082)
  • MODELS_DIR: Directory containing NetCDF model data (mounted as /nc)
  • TOPOGRAPHY_DIR: Directory for topography data
  • WEB_INTERFACE_USERNAME: Username for web interface
  • WEB_INTERFACE_PASSWORD: Password for web interface
  • SMTP_FROM: Email sender for notifications
  • SMTP_TO: Email recipient for notifications

​
Volumes

  • /data/archives:/nc:ro: NetCDF data (read-only)
  • /modms/nc:/topography:ro: Topography data (read-only, main server only)

​
Ports

  • 8082:8082: Connector service port

​
Registry Integration

The connector works with the registry system:
  1. Main server reads registry.json to determine data locations
  2. For queries to archived data, the main server connects to the archive server’s connector (port 8082)
  3. The connector on the archive server serves the requested data
  4. Results are returned to the main server and then to the client
Each MAMS instance (main and archive servers) must have a connector service deployed. This enables the distributed query system.

​
Query Flow

Client Request
    ↓
Main MAMS Server (modms service)
    ↓
Check registry.json for data location
    ↓
If data on archive server:
    ↓
Connect to Archive Server Connector (port 8082)
    ↓
Archive Server Connector serves data
    ↓
Results returned to Main Server
    ↓
Results returned to Client

​
Deployment Requirements

​
Main Server

  • Deploys both modms and connector services
  • Connector listens on port 8082
  • Connector can query local data and route to archive servers

​
Archive Servers

  • Deploy only connector service
  • Connector listens on port 8082
  • Connector serves data from local /data/archives directory
  • No full ModMS API service needed
Archive servers must have the connector service running for the main server to access their data. If the connector is down, queries for data on that server will fail.

​
Troubleshooting

​
Check Connector Status

# On main server or archive server
docker service ps modms_connector

# Check logs
docker service logs modms_connector --tail 100

​
Verify Connectivity

From main server, test connection to archive server connector: 
# Test connector endpoint (if available)
curl http://138.201.49.117:8082/health

​
Common Issues

  • Connector not responding: Check if service is running and port 8082 is accessible
  • Connection refused: Verify firewall rules allow port 8082
  • Data not found: Check registry.json to ensure correct server mapping
  • Authentication errors: Verify credentials match between main and archive servers