ansible-proxy-chain/openspec/changes/archive/2026-04-22-auto-generate-surge-config/proposal.md

Why

Currently ports and passwords are manually configured. Randomizing them on first deploy reduces the chance of detection and simplifies initial setup. After deployment, a usable Surge client configuration should be automatically generated with the actual connection parameters — no manual placeholder replacement.

What Changes

• Generate random SS port, SS password, Trojan port, and Trojan password during first playbook run (persisted so subsequent runs don't regenerate)
• Convert docs/surge-client.conf from a static reference file to a Jinja2 template rendered by Ansible with actual deployment parameters
• Output the generated Surge config to a local file after deployment
• Remove manual placeholder approach from the reference config

Capabilities

New Capabilities

• auto-credentials: Random port and password generation with persistence across playbook runs
• surge-config-gen: Ansible-driven Surge client configuration generation from deployed parameters

Modified Capabilities

• shadowsocks-relay: SS port and password become auto-generated instead of manually configured
• trojan-landing: Trojan port and password become auto-generated instead of manually configured
• proxy-rules: Surge config is now generated from template, not a static reference file

Impact

• group_vars/relay.yml and group_vars/landing.yml no longer require manual password/port configuration
• group_vars/vault.yml.example simplified (no manual password entry needed)
• docs/surge-client.conf replaced by roles/surge-config/templates/surge-client.conf.j2
• Generated Surge config output to output/surge-client.conf on the Ansible controller after each run
• Existing Ansible Vault workflow still supported for users who prefer manual credentials