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:

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

# 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