Provision a web ingress proxy (NGINX)

This runbook documents how to provision an additional NGINX web ingress proxy comparable to web.core.lef.

It is written so we can reliably spin up a second proxy using the same layout and conventions (see NGINX ingress (public vs internal)).

Avoid VIP conflicts

Never have the same ingress VIP bound on two servers at the same time. If both hosts answer the same VIP, traffic becomes unpredictable.

Inputs (decide up front)

• The new proxy hostname and server page (Reference).
• A unique Core LAN IP for the new proxy (see Core LAN).
• Which public ingress VIPs it should serve:
  • Warm standby / replacement: the existing VIPs move to the new proxy during cutover.
  • Split ingress / expansion: allocate new VIPs and update the firewall mappings accordingly.
• Whether it should also serve any VPN-only ingress VIPs (public DNS reachable only when on VPN; see Firewall & public ingress (reference)).

Preconditions

• You are on VPN/LAN (see VPN access (support)).
• You have SSH access to the existing proxy (and to the new one once provisioned).
• You can coordinate EVEO-side changes when required (firewall mappings and/or VM provisioning).

Procedure

1) Create/update the server definition page (Reference)

Create the new server page under /reference/infra/servers/ using the canonical server template:

• Template: src/content/docs/reference/_templates/server.mdx

Populate only confirmed values. If any details are unknown (VMID, sizing, etc), omit them and leave a {/* TODO: ... */}.

2) Provision the VM (platform)

Provision a new Debian VM alongside the existing np-* VMs (see Private cloud hypervisor).

3) Configure the base network (Core LAN IP)

Configure a unique static IP in 192.168.20.0/24 with the Core LAN gateway and DNS resolver(s).

Authoritative “what IPs exist” lives in Core LAN. Record the new proxy’s LAN IP in its server page.

4) Deploy ingress VIPs (if needed)

Follow the VIP runbook:

• Virtual IPs (VIPs)

Notes:

• Warm standby: define the VIP stanzas but do not bring them up until cutover.
• Split ingress: update Firewall & public ingress (reference) with the new public IP → VIP mapping in the same PR.

5) Install and configure NGINX

Use the listener-separated layout and example files from:

• NGINX ingress (public vs internal)

Keep configuration structurally identical between proxies where possible. Differences should be limited to:

• host-specific IP addresses in listen ...
• certificate paths and any host-specific paths

6) Certificates and TLS material

Ensure the proxy has the required certificates/keys for the public hostnames it will serve. See:

• SSL certificates for web servers

7) Validation checklist

Start with the test checklist in the ingress runbook:

• NGINX ingress (public vs internal)

Then validate the specific public hostnames you expect to serve by targeting the VIP directly (from a host that can reach it):

curl -I http://<vip-ip>/ -H 'Host: <public-hostname>'
openssl s_client -connect <vip-ip>:443 -servername <public-hostname>

8) Cutover (warm standby only)

If you are moving existing VIPs from one proxy to another:

1. Confirm the new proxy is ready (NGINX config + certificates + health checks).
2. Remove the VIP(s) from the old proxy (or bring them down) and ensure they no longer appear in ip -br addr.
3. Bring up the VIP(s) on the new proxy.
4. Re-run the validation checklist.

Documentation follow-ups

• Keep Firewall & public ingress (reference) authoritative for public IP → VIP allocations.
• Ensure the new proxy server page is present under Servers and linked from the relevant section indexes as needed.

Related

web.core.lef (facts) NGINX ingress layout Virtual IPs (VIPs)