# Service Registry

The service registry is a simple key-value mapping that assigns service numbers to service names within a namespace.

## Location

The service registry is stored in the namespace station NFS export:
- Production: `/volume1/{namespace}/station/prod/service-registry`
- Test: `/volume1/{namespace}/station/test/service-registry`

**Implementation:** The service registry is automatically created by `machine/scripts/setup_station.sh:create_service_registry()` during the machine setup process. This function:
1. Scans existing system UIDs to discover deployed services
2. Creates the registry file with proper ownership (station-prod user)  
3. Populates it with discovered service mappings

**Access Paths:**
- NFS location: `/volume1/{namespace}/station/prod/service-registry`
- Local mount: `/mnt/docker/state/service-registry` (accessed by `machine/scripts/lib.sh:calculate_service_uid()`)
- XDG access: `~/.local/state/{namespace}/@station/service-registry`

## Format

The registry uses a simple `key=value` format, one service per line:

```
# Service Registry for dynamicalsystem namespace
# Format: service_name=service_number
# Service 0 is reserved for station (namespace infrastructure)

gazette=1
lldap=2
redis=3
prometheus=4
grafana=5
```

## Rules

1. **Service 0 is reserved** for the namespace station (infrastructure)
2. **Service names** must be lowercase alphanumeric with hyphens allowed
3. **Service numbers** must be unique within a namespace (1-99)
4. **Comments** start with `#` and are ignored
5. **Empty lines** are ignored

## Usage

### Reading the Registry

Services and tools read the registry to determine their service number:

```bash
# Get service number for 'lldap'
service_num=$(grep "^lldap=" /volume1/dynamicalsystem/station/prod/service-registry | cut -d= -f2)
```

### Adding a New Service

1. Edit the registry file on the NAS
2. Add a new line with the next available service number
3. Ensure no conflicts with existing services

### Example Workflow

```bash
# SSH to NAS
ssh admin@nas.local

# Edit registry
sudo vi /volume1/dynamicalsystem/station/prod/service-registry

# Add new service
echo "caddy=6" >> /volume1/dynamicalsystem/station/prod/service-registry
```

## Integration with tinsnip

The `machine/lib.sh` script automatically consults the service registry when calculating UIDs:

1. If service name is "station", use service number 0
2. Otherwise, check the registry file
3. If not found in registry, fall back to hardcoded values (for backward compatibility)
4. If still not found, return an error

## Future Enhancements

The station service (S=0) could eventually provide:
- REST API for service registration
- Web UI for registry management
- Service discovery endpoints
- Port allocation tracking