> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2.ard.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector Service

> Connector service enabling distributed queries across MAMS servers

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

<Note>
  Each MAMS instance (main and archive servers) must have a connector service deployed. This enables the distributed query system.
</Note>

## 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

<Warning>
  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.
</Warning>

## Troubleshooting

### Check Connector Status

```bash theme={null}
# 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:

```bash theme={null}
# 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

## Related Documentation

* [MAMS Overview](/data-ai/modms/mams) - MAMS system overview
* [MAMS Deployment](/data-ai/modms/mams/deployment) - Deployment configuration
* [MAMS Registry](/data-ai/modms/mams/registry) - Registry system documentation