tftsr_ai/roles/nginx/README.md

Role: nginx

Purpose

Manage NGINX reverse proxy configurations on nginx_proxy (nginx_proxy_ip) for all platform services.

Managed Configurations

Config File	Service	Upstream Target
vault.conf	Vault	<ai_server_ip>:<vault_port>
ollama-api.conf	Ollama API	<ai_server_ip>:<ollama_port>
keycloak-proxy.conf	Keycloak	<ai_server_ip>:<keycloak_port>

Each configuration file is placed in /etc/nginx/conf.d/ on the proxy host.

SSL Certificates

TLS certificates for *.<domain> are stored at:

• Certificate: /etc/nginx/ssl/<domain>.crt
• Private key: /etc/nginx/ssl/<domain>.key

All reverse proxy configs reference these paths (via nginx_ssl_cert / nginx_ssl_key variables) for TLS termination.

How to Add a New Service

1. Create a new config file following the existing template pattern:

   upstream new_service {
   server {{ ai_server_ip }}:<target_port>;
   }
   
   server {
   listen 443 ssl;
   server_name new-service.{{ domain }};
   
   ssl_certificate     {{ nginx_ssl_cert }};
   ssl_certificate_key {{ nginx_ssl_key }};
   
   location / {
       proxy_pass http://new_service;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
   }
   }
   

2. Add the template to the role's templates/ directory

3. Add the DNS record via the coredns role

Configuration Validation

Before reloading NGINX, the role runs:

nginx -t

The reload is only performed if the configuration test passes. This prevents broken configs from taking down the proxy.

Tags

ansible-playbook playbooks/site.yml --tags nginx