ansible-proxy-chain/openspec/changes/archive/2026-04-22-add-relay-domain-for-surge-config/design.md

Context

The Surge template at templates/surge-client.conf.j2 defines the relay proxy as:

Relay-SS = ss, {{ hostvars[groups['relay'][0]]['ansible_host'] }}, ...

This hardcodes the relay server's IP. The landing server already uses a trojan_domain variable for its proxy entry, so the relay should follow the same pattern for consistency and operational flexibility.

Goals / Non-Goals

Goals:

• Introduce a relay_domain variable in group_vars/relay.yml
• Use it in the Surge template instead of the raw IP
• Keep the variable pattern consistent with the existing trojan_domain approach

Non-Goals:

• DNS or TLS configuration for the relay server
• Changing the Shadowsocks protocol or connection behavior

Decisions

Define relay_domain in group_vars/relay.yml

The relay domain is specific to the relay server, so it belongs in group_vars/relay.yml rather than all.yml. The Surge template already reads variables from hostvars for the relay (e.g., ss_port, ss_password), so relay_domain will be read the same way.

Use a simple relay_domain variable, not a lookup

Unlike ss_port which needs a random password lookup, the domain is a static value set by the user. A plain string variable is sufficient.

Risks / Trade-offs

• [DNS dependency] → The relay domain must resolve to the relay server's IP; this is an operational prerequisite outside Ansible's scope