Reverse Proxy

Deploy a reverse proxy in front of self-hosted applications, terminating TLS and enforcing an IP allow list per site. These interchangeable implementations are available:

• Caddy
• Nginx Proxy Manager

Every implementation runs in the same {{ cs_rp_container_name }} Docker container name and reads the same reverse_proxy Ansible hosts group, the same shared variables, and the same cs_rp_hosts per-application host definitions: only the backend-specific variables, the Vault-driven credentials, and how each host definition is applied differ. See the linked pages for those details.

Ansible hosts group: reverse_proxy

Choosing an implementation

playbook.yml's Reverse Proxy play sets cs_rp_which_one to select which implementation is deployed. Its value must be either caddy or nginx_proxy_manager, and it drives which task files are imported for every reverse proxy tag:

tasks/reverse_proxy/{{ cs_rp_which_one }}/main.yml
tasks/reverse_proxy/{{ cs_rp_which_one }}/restic_backup.yml
tasks/reverse_proxy/{{ cs_rp_which_one }}/restic_restore.yml
tasks/reverse_proxy/{{ cs_rp_which_one }}/cleanup.yml

The default set in playbook.yml is nginx_proxy_manager. To deploy Caddy instead without editing playbook.yml, override it on the command line:

uv --offline run --no-sync --no-progress ansible-playbook playbook.yml --tags reverse_proxy_install \
    --extra-vars "cs_rp_which_one=caddy"

Variables: shared

Option	Type	Description	Default
cs_rp_container_name	string	Docker container name	reverse_proxy
cs_rp_hosts	dict	Per-host proxy host definitions	{}
cs_rp_restic_cluster_name	string	Restic cluster name	{{ cs_cluster_name }}
cs_rp_restic_node_name	string	Restic backup node name	{{ inventory_hostname }}
cs_rp_restic_repo_name	string	Restic repository name	reverse_proxy
cs_rp_cidr_allow_list	list[string]	CIDRs/IPs allowed to reach every site	The cluster CIDR and VPN CIDR (from Vault), plus 0.0.0.0/0

cs_rp_hosts.<Application Name>

Host definitions are set once, per host, in inventory.yml, and are shared by every implementation. Which keys are honored, and how, is implementation-specific: see Caddy or Nginx Proxy Manager for the full key reference.

Vault configurations

• key: {{ cs_project_code }}/application-deployer/clusters/{{ Lab Name or Cluster name }}/hosts/{{ hostname }}/apps/reverse-proxy/config

Every implementation requires a default certificate and private_key at the top level of this key. Each reads optional per-application certificate overrides from this key under an apps map keyed by application name (matching a key in cs_rp_hosts), falling back to the default certificate and private_key if not provided for an application. Each reads a shared management_port for their admin interface; Nginx Proxy Manager also reads its admin credentials from the same key. See each implementation's page for its exact Vault payload shape.

Restic backup and restore

Every implementation backs up and restores its data directory with the restic_backup_restore_sftp module, using the restic cluster/node/repo variables listed above, stopping and restarting the {{ cs_rp_container_name }} container around the backup. See each implementation's page for the exact directory contents covered.

Tags

These tags apply to whichever implementation cs_rp_which_one selects:

• reverse_proxy: Deploy the reverse proxy and run its Restic backup.
• reverse_proxy_install: Deploy the reverse proxy only.
• reverse_proxy_restic_backup: Run Restic backup for the reverse proxy.
• reverse_proxy_restic_restore: Restore the reverse proxy's data from the latest Restic snapshot.
• dangerously_cleanup_reverse_proxy: Destructive. Permanently removes the reverse proxy's Docker container, closes its UFW ports, and deletes its data directory. Never included by the plain reverse_proxy tag. See each implementation's page for its exact cleanup steps.

Deployment

uv sync --all-extras --all-packages --no-progress
uv --offline run --no-sync --no-progress ansible-galaxy install -r requirements.yml
uv --offline run --no-sync --no-progress ansible-playbook playbook.yml --tags reverse_proxy_install