ansible-proxy-chain/openspec/changes/archive/2026-04-22-add-nginx-fallback-for-trojan/design.md

Context

The trojan-go config template at roles/trojan/templates/trojan-config.json.j2 sets remote_port: {{ trojan_fallback_port }} (default 8080). This is the port trojan-go forwards non-authenticated HTTPS traffic to for camouflage. Currently nothing listens on this port, so trojan-go fails to operate correctly.

Goals / Non-Goals

Goals:

• Provide a working HTTP fallback on port 8080 for trojan-go camouflage
• Keep the nginx setup minimal — a generic static page, no reverse proxy logic

Non-Goals:

• Full nginx reverse proxy or multi-site configuration
• Serving the actual Let's Encrypt TLS site on this port (trojan-go handles TLS on 443)

Decisions

Add nginx tasks inside the trojan role rather than a separate role

The nginx fallback is tightly coupled to the trojan deployment — it exists solely as camouflage for trojan-go. Adding tasks to the existing trojan role keeps the relationship clear and avoids an extra role.

Use a simple inline nginx config, not a full vhost template directory

The fallback only needs a minimal server block: listen on trojan_fallback_port, serve a generic static HTML page. A single nginx-fallback.conf.j2 template deployed to /etc/nginx/conf.d/ is sufficient.

Allow the fallback port through UFW

The base role handles firewall rules. The landing role already opens port 80 via allowed_ports. Add trojan_fallback_port to the landing allowed_ports list so nginx is reachable.

Risks / Trade-offs

• [nginx not installed] → Installing nginx adds a dependency; ensure the task installs it before deploying the config
• [port conflict] → trojan_fallback_port is hardcoded as 8080 in defaults; if another service uses this port, nginx will fail to start