4
Edge-Proxy-Install
gsadmin edited this page 2026-08-08 22:58:57 +00:00

Edge Proxy Install

Nginx UI is the recommended edge: a web console for nginx with ACME issuance and renewal built in. It runs on Windows and Linux.

The site config for ExecuteR is at the bottom of this page.

Windows — scripted install as a service

Run in an elevated PowerShell. The script is idempotent — re-run it any time to upgrade the binary or reassert the service settings.

It downloads with WebClient, installs to %ProgramFiles%\NginX-UI, puts the NSSM service wrapper in System32, and registers an automatic service with restart-on-failure actions.

$ErrorActionPreference = 'Stop'
$installDir  = "$env:ProgramFiles\NginX-UI"
$serviceName = 'nginx-ui'
$web = New-Object System.Net.WebClient

# -- NSSM service wrapper in System32 (skipped when already present) --------
$nssm = "$env:SystemRoot\System32\nssm.exe"
if (-not (Test-Path $nssm)) {
    $zip = "$env:TEMP\nssm.zip"
    $web.DownloadFile('https://nssm.cc/release/nssm-2.24.zip', $zip)
    Expand-Archive $zip "$env:TEMP\nssm" -Force
    Copy-Item "$env:TEMP\nssm\nssm-2.24\win64\nssm.exe" $nssm
    Remove-Item $zip, "$env:TEMP\nssm" -Recurse -Force
}

# -- Nginx UI binary (re-run to upgrade; adjust -amd64 for other arches) ----
New-Item -ItemType Directory -Force $installDir, "$installDir\logs" | Out-Null
$zip = "$env:TEMP\nginx-ui.zip"
$web.DownloadFile('https://github.com/0xJacky/nginx-ui/releases/latest/download/nginx-ui-windows-amd64.zip', $zip)
if (Get-Service $serviceName -ErrorAction SilentlyContinue) { & $nssm stop $serviceName | Out-Null }
Expand-Archive $zip $installDir -Force
Remove-Item $zip

# -- Automatic service with failure actions (settings reasserted each run) --
if (-not (Get-Service $serviceName -ErrorAction SilentlyContinue)) {
    & $nssm install $serviceName "$installDir\nginx-ui.exe" '-config' "`"$installDir\app.ini`""
}
& $nssm set $serviceName AppDirectory   $installDir
& $nssm set $serviceName DisplayName    'Nginx UI'
& $nssm set $serviceName Description    'Web console for nginx (ExecuteR edge)'
& $nssm set $serviceName Start          SERVICE_AUTO_START
& $nssm set $serviceName AppExit        Default Restart
& $nssm set $serviceName AppRestartDelay 5000
& $nssm set $serviceName AppStdout      "$installDir\logs\service.log"
& $nssm set $serviceName AppStderr      "$installDir\logs\service.log"
& $nssm set $serviceName AppRotateFiles 1
& $nssm set $serviceName AppRotateBytes 10485760
sc.exe failure     $serviceName reset= 86400 actions= restart/5000/restart/5000/restart/30000 | Out-Null
sc.exe failureflag $serviceName 1 | Out-Null

& $nssm start $serviceName
Write-Host "Nginx UI running - finish setup at http://localhost:9000"

Then open http://localhost:9000, finish the setup wizard, and add the ExecuteR site below.

Nginx itself must also be present (unzip from nginx.org to C:\nginx and point the wizard at it). Wrap it as a service the same way: nssm install nginx C:\nginx\nginx.exe plus the same Start, AppExit and sc.exe failure lines with nginx as the name.

Linux — Docker

The edge owns 80 and 443 — the one place well-known host ports are correct. The official image bundles nginx and the console in one container.

#=============================================================================
# EDGE - Nginx UI reverse proxy (host-level TLS edge with console)
#=============================================================================
name: '${STACK_NAME:-stk-edge-nginxui-00001}'

networks:
  EXTERNAL:
    name: EDGE-EXTERNAL
    driver: bridge
    internal: false
    attachable: true

services:
  Proxy:
    image: '${NGINXUI_IMAGE:-uozi/nginx-ui}:${NGINXUI_VERSION:-latest}'
    container_name: EDGE-PROXY-00001
    restart: unless-stopped
    logging:
      driver: 'local'
    networks:
      EXTERNAL:
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
      - "${STACK_BINDMOUNTROOT:-/mnt/docker/stacks}/${STACK_NAME:-stk-edge-nginxui-00001}/Proxy/Config/nginx:/etc/nginx:rw"
      - "${STACK_BINDMOUNTROOT:-/mnt/docker/stacks}/${STACK_NAME:-stk-edge-nginxui-00001}/Proxy/Data/nginx-ui:/etc/nginx-ui:rw"

Matching .env:

STACK_NAME=stk-edge-nginxui-00001
STACK_BINDMOUNTROOT=/mnt/docker/stacks
NGINXUI_IMAGE=uozi/nginx-ui
NGINXUI_VERSION=latest

docker compose up -d, then open http://<host> and finish the setup wizard. Add the site below in the console and let Nginx UI request the certificate.

The nginx config for ExecuteR

It comes in two files, and the split matters in Nginx UI:

  1. executer-http.conf — just the WebSocket upgrade map, which must be included at http{} level. In Nginx UI this goes under Manage Configs → conf.d/executer-http.conf. On plain nginx, drop it in /etc/nginx/conf.d/. Do not paste it into the site.
  2. executer.conf — everything else: the rate-limit zones, upstreams and server blocks. This is the site: Manage Sites in Nginx UI, or sites-available/ on plain nginx.

The maintained copies live at src/Infra/nginx/ in the repository. Replace control.example.com, 10.0.0.10 and the certificate paths (Nginx UI fills the cert paths for you when it issues the certificate).

executer-http.conf — Manage Configs / conf.d (click to expand)
# "upgrade" for WebSocket requests, "close" otherwise. Must be included at
# http{} level. If your nginx.conf already defines this map, delete the
# duplicate here or nginx will refuse to start.
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}
executer.conf — Manage Sites (click to expand)
# --- Rate-limit zones -------------------------------------------------------
limit_req_zone $binary_remote_addr zone=executer_enroll:10m rate=10r/m;
limit_req_zone $binary_remote_addr zone=executer_auth:10m   rate=20r/m;

# --- Upstreams --------------------------------------------------------------
# If the backend runs with TLS_SELF_SIGNED=1, switch its proxy_pass to
# https:// and add `proxy_ssl_verify off;` (the hop stays encrypted; the
# self-signed roots simply are not distributed) - or import the exported
# root+intermediate and use proxy_ssl_trusted_certificate + proxy_ssl_verify
# on, re-importing when the chain rotates at expiry.
upstream executer_webui {
    server 10.0.0.10:13080;
    keepalive 16;
}

upstream executer_api {
    server 10.0.0.10:19080;
    keepalive 16;
}

upstream executer_nats {
    server 10.0.0.10:19222;
    keepalive 32;
}

# --- HTTP: redirect to HTTPS ------------------------------------------------
server {
    listen 80;
    listen [::]:80;
    server_name control.example.com;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/acme;
        default_type "text/plain";
    }

    location / {
        return 301 https://$server_name$request_uri;
    }
}

# --- HTTPS ------------------------------------------------------------------
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name control.example.com;

    ssl_certificate     /etc/nginx/ssl/control.example.com/fullchain.cer;
    ssl_certificate_key /etc/nginx/ssl/control.example.com/private.key;

    access_log /var/log/nginx/control.example.com_access.log;
    error_log  /var/log/nginx/control.example.com_error.log;

    # The backend only honors forwarded headers from trusted proxy
    # addresses (private networks by default) - make sure THIS host is
    # covered by TRUSTED_PROXIES / TRUSTED_NETWORKS.
    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;
    proxy_set_header X-Forwarded-Host  $host;
    proxy_set_header X-Forwarded-Port  $server_port;
    proxy_set_header X-Forwarded-Prefix /;

    # WebSocket upgrade (safe site-wide).
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    # Inventory payloads and file uploads can be large.
    client_max_body_size 0;

    add_header X-Content-Type-Options    "nosniff"          always;
    add_header X-Frame-Options           "SAMEORIGIN"       always;
    add_header Referrer-Policy           "same-origin"      always;
    add_header Strict-Transport-Security "max-age=31536000" always;

    # Optional: restrict the whole site to known networks.
    # allow 10.0.0.0/8;         # RFC1918 - internal
    # allow 172.16.0.0/12;      # RFC1918 - internal
    # allow 192.168.0.0/16;     # RFC1918 - internal
    # allow 100.64.0.0/10;      # CGNAT - carrier / overlay networks
    # allow 203.0.113.0/24;     # office egress
    # deny  all;

    # NATS WebSocket: agents (long-lived - do not time out).
    location = /messaging/agent {
        proxy_pass http://executer_nats;
        proxy_read_timeout  1h;
        proxy_send_timeout  1h;
        proxy_buffering     off;
    }

    # NATS WebSocket: browsers.
    location = /messaging/browser {
        proxy_pass http://executer_nats;
        proxy_read_timeout  1h;
        proxy_send_timeout  1h;
        proxy_buffering     off;
    }

    # Enrollment: rate limited, no caching.
    location ^~ /api/enrollment/ {
        limit_req zone=executer_enroll burst=5 nodelay;
        proxy_pass http://executer_api;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_read_timeout 300s;
        proxy_buffering    off;
    }

    # Sign-in: rate limited (also covers the OIDC callback).
    location ^~ /api/auth/ {
        limit_req zone=executer_auth burst=10 nodelay;
        proxy_pass http://executer_api;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }

    # Backend API.
    location ^~ /api/ {
        proxy_pass http://executer_api;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_read_timeout 120s;
    }

    # WebUI (everything else).
    location / {
        proxy_pass http://executer_webui;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

After the install

Point DNS at the edge and forward the three ExecuteR routes. The proxy host is trusted by the backend automatically when it sits on a private address. Details in Networking and TLS.