Scaling (IaC/queue groups), self-signed CA auto-trust + public-IP SANs, clean uninstall #9

Merged
gsadmin merged 4 commits from dev into main 2026-08-09 21:50:14 +00:00
40 changed files with 1445 additions and 79 deletions
+2 -2
View File
@@ -12,7 +12,7 @@
# PRODUCTION SETUP:
# 1. cp .env.example .env (or run scripts/New-LocalSecrets.ps1)
# 2. Fill INITIAL_ADMIN_PASSWORD and NATS_ACCOUNT_SIGNING_SEED
# 3. docker compose up -d --build
# 3. docker compose -f IaC/compose/docker-compose.yml up -d --build (or ./scripts/deploy.sh)
#
#=============================================================================
@@ -44,7 +44,7 @@ REGISTRY_TOKEN=
NATS_IMAGE=nats
NATS_VERSION=2.12-alpine@sha256:7cef1bd3fed6034e95cf6e6bc9c28c5afa6dc58e9fb778dd7924a1ac62569f2d
# Optional in-stack reverse proxy (docker-compose.proxy.yml, opt-in)
# Optional in-stack reverse proxy (IaC/compose/docker-compose.proxy.yml, opt-in)
NGINX_IMAGE=nginx
NGINX_VERSION=1.29-alpine
PROXY_HTTP_PORT=18080
+56
View File
@@ -0,0 +1,56 @@
# Infrastructure as Code
Deployment manifests for ExecuteR, in increasing order of scale:
| Target | Folder | Use it for |
|--------|--------|-----------|
| **Docker Compose** | [`compose/`](compose) | A single host. The default; `scripts/deploy.sh` drives it. |
| **Docker Swarm** | [`swarm/`](swarm) | A few nodes, replicas behind one VIP, minimal orchestration. |
| **Kubernetes** | [`k8s/`](k8s) | Many nodes, HPA, rolling updates, cloud/multi-cloud. |
All three run the **same images** (`executer-backend`, `executer-webui`) and
the same NATS. They differ only in how many replicas run and how state is
shared. See the [Scaling and HA](../../../wiki/Scaling-and-HA) wiki page for
the full picture and diagram.
## What is stateless vs. stateful
Scaling past one backend/webui instance is safe because the realtime fan-out
is NATS's job, not the backend's — agents and browsers hold their WebSocket
to NATS through the edge, so replicas don't multiply that load.
**Stateless (scale freely):**
- **WebUI** — pure SSR/static; any number of replicas.
- **Backend REST** — cookie auth, no server-side session store. Round-robin;
no sticky sessions needed.
- **Backend ingest workers** — subscribe with a NATS **queue group**, so each
presence/inventory/job message is processed by exactly one replica.
**Stateful / single-owner (needs shared infrastructure):**
- **Database** — must be Postgres or SQL Server (not the SQLite default) so
all backends share one store.
- **Data Protection key ring** — all backends must share it (cookies, CSRF,
encrypted secret blobs). Mount `DATAPROTECTION_PATH` on shared storage
(CephFS/MicroCeph, NFS) — every manifest here does.
- **Schedule worker** — must run in exactly one place or schedules fire N
times. Run web/API replicas with `SCHEDULE_WORKER=0` and one dedicated
**worker** replica with `SCHEDULE_WORKER=1` (swarm/k8s do this).
- **NATS + JetStream** — a 3-node cluster (JetStream R3) for HA; a
supercluster with gateways spans regions/clouds.
## Cross-cutting prerequisites for multi-instance
- **Shared storage** for the key ring (and NATS JetStream if not clustered):
MicroCeph/CephFS or NFS, exposed as a Swarm volume driver or a k8s
`ReadWriteMany` StorageClass.
- **A private overlay** between nodes/regions — WireGuard via
[Tailscale](https://tailscale.com) or [NetBird](https://netbird.io) — so
NATS cluster/gateway routes and the DB travel encrypted across sites
without public exposure.
- **Service discovery** — Swarm and k8s both provide DNS
(`tasks.<service>` / `<service>.<ns>.svc`); NATS cluster routes and DB
hosts use those names.
- **One edge / single DNS name** terminating TLS and load-balancing the
replicas (see [Networking and TLS](../../../wiki/Networking-and-TLS)).
+27
View File
@@ -0,0 +1,27 @@
# Compose (single host)
The default single-host deployment.
```bash
# from the repository root
./scripts/deploy.sh # pull images (or build), start
./scripts/deploy.sh --with-proxy --host control.example.com
# or directly
cp .env.example .env # then fill secrets
docker compose -f IaC/compose/docker-compose.yml up -d --build
```
Files:
- `docker-compose.yml` — nats + backend + webui. Relative build contexts and
bind mounts are authored against this folder (`../..` = repo root), so run
it from the repository root as shown.
- `docker-compose.dev.yml` — development overrides (`… -f docker-compose.yml
-f docker-compose.dev.yml`).
- `docker-compose.proxy.yml` — opt-in in-stack nginx edge (`deploy.sh
--with-proxy`).
For more than one backend/webui replica, move up to
[`../swarm`](../swarm) or [`../k8s`](../k8s) — a single-host Compose file
can't share the Data Protection key ring or split off a schedule worker.
@@ -55,8 +55,8 @@ services:
volumes:
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- ./src/Infra/nats/nats.conf:/etc/nats/nats.conf:ro
- ./secrets/nats/resolver.conf:/etc/nats/resolver.conf:ro
- ../../src/Infra/nats/nats.conf:/etc/nats/nats.conf:ro
- ../../secrets/nats/resolver.conf:/etc/nats/resolver.conf:ro
- "${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/NATS/JetStream:/data/jetstream:rw"
- "${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/NATS/Resolver:/data/resolver:rw"
healthcheck:
@@ -76,7 +76,7 @@ services:
pull_policy: '${IMAGE_PULL_POLICY:-missing}'
container_name: EXECUTER-API-00001
build:
context: .
context: ../..
dockerfile: src/Infra/backend/Dockerfile
args:
UNIFIED_VERSION: ${UNIFIED_VERSION:-0.0.0.0}
@@ -169,7 +169,7 @@ services:
pull_policy: '${IMAGE_PULL_POLICY:-missing}'
container_name: EXECUTER-WEB-00001
build:
context: .
context: ../..
dockerfile: src/Infra/webui/Dockerfile
args:
UNIFIED_VERSION: ${UNIFIED_VERSION:-0.0.0.0}
+52
View File
@@ -0,0 +1,52 @@
#=============================================================================
# ExecuteR - Kubernetes: namespace, config, secrets, shared key ring
#=============================================================================
apiVersion: v1
kind: Namespace
metadata:
name: executer
---
apiVersion: v1
kind: ConfigMap
metadata:
name: executer-config
namespace: executer
data:
ASPNETCORE_URLS: 'http://0.0.0.0:8080'
DATABASE_PROVIDER: 'postgres'
DATABASE_CONNECTION_STRING: 'Host=executer-db;Database=executer;Username=executer;Password=$(POSTGRES_PASSWORD)'
DATAPROTECTION_PATH: '/keys'
NATS_URL: 'nats://executer-nats:4222'
NATS_WS_PROXY: 'ws://executer-nats:9222'
NATS_MONITOR_URL: 'http://executer-nats:8222'
TRUST_PROXY: '1'
PUBLIC_SERVER_URL: 'https://control.example.com'
---
# Fill these in (or use a sealed-secret / external-secrets operator).
# NATS keys: `kubectl run … executer-backend nats-auth init` once, then paste.
apiVersion: v1
kind: Secret
metadata:
name: executer-secrets
namespace: executer
type: Opaque
stringData:
POSTGRES_PASSWORD: 'change-me'
NATS_ACCOUNT_SIGNING_SEED: 'SA...'
NATS_ACCOUNT_PUBLIC_KEY: 'A...'
INITIAL_ADMIN_USERNAME: 'admin'
INITIAL_ADMIN_PASSWORD: 'change-me'
---
# Shared Data Protection key ring: ALL backend/worker pods read it, so the
# StorageClass must support ReadWriteMany (CephFS/MicroCeph, NFS).
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: executer-keyring
namespace: executer
spec:
accessModes: ['ReadWriteMany']
storageClassName: 'cephfs' # set to your RWX StorageClass
resources:
requests:
storage: 1Gi
+97
View File
@@ -0,0 +1,97 @@
#=============================================================================
# ExecuteR - Kubernetes: Postgres + NATS (JetStream cluster)
# For production NATS, prefer the official Helm chart; this hand StatefulSet
# is a self-contained, adaptable equivalent.
#=============================================================================
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: executer-db
namespace: executer
spec:
serviceName: executer-db
replicas: 1
selector: { matchLabels: { app: executer-db } }
template:
metadata: { labels: { app: executer-db } }
spec:
containers:
- name: postgres
image: postgres:17-alpine
env:
- { name: POSTGRES_DB, value: executer }
- { name: POSTGRES_USER, value: executer }
- name: POSTGRES_PASSWORD
valueFrom: { secretKeyRef: { name: executer-secrets, key: POSTGRES_PASSWORD } }
ports: [{ containerPort: 5432 }]
volumeMounts: [{ name: data, mountPath: /var/lib/postgresql/data }]
volumeClaimTemplates:
- metadata: { name: data }
spec:
accessModes: ['ReadWriteOnce']
resources: { requests: { storage: 20Gi } }
---
apiVersion: v1
kind: Service
metadata: { name: executer-db, namespace: executer }
spec:
selector: { app: executer-db }
ports: [{ port: 5432, targetPort: 5432 }]
---
apiVersion: v1
kind: Service
metadata: { name: executer-nats, namespace: executer }
spec:
selector: { app: executer-nats }
ports:
- { name: client, port: 4222, targetPort: 4222 }
- { name: ws, port: 9222, targetPort: 9222 }
- { name: monitor, port: 8222, targetPort: 8222 }
---
# Headless service for peer discovery (JetStream clustering).
apiVersion: v1
kind: Service
metadata: { name: executer-nats-peers, namespace: executer }
spec:
clusterIP: None
selector: { app: executer-nats }
ports: [{ name: cluster, port: 6222, targetPort: 6222 }]
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: executer-nats
namespace: executer
spec:
serviceName: executer-nats-peers
replicas: 3
selector: { matchLabels: { app: executer-nats } }
template:
metadata: { labels: { app: executer-nats } }
spec:
containers:
- name: nats
image: nats:2-alpine
command:
- nats-server
- '--name=$(POD_NAME)'
- '--jetstream'
- '--store_dir=/data'
- '--cluster_name=executer'
- '--cluster=nats://0.0.0.0:6222'
- '--routes=nats://executer-nats-0.executer-nats-peers:6222,nats://executer-nats-1.executer-nats-peers:6222,nats://executer-nats-2.executer-nats-peers:6222'
- '--http_port=8222'
env:
- name: POD_NAME
valueFrom: { fieldRef: { fieldPath: metadata.name } }
ports:
- { containerPort: 4222 }
- { containerPort: 9222 }
- { containerPort: 8222 }
- { containerPort: 6222 }
volumeMounts: [{ name: jetstream, mountPath: /data }]
volumeClaimTemplates:
- metadata: { name: jetstream }
spec:
accessModes: ['ReadWriteOnce']
resources: { requests: { storage: 10Gi } }
+112
View File
@@ -0,0 +1,112 @@
#=============================================================================
# ExecuteR - Kubernetes: backend (API) replicas, scheduler worker, WebUI
# Replace REGISTRY / VERSION before applying (or kustomize the image).
#=============================================================================
apiVersion: apps/v1
kind: Deployment
metadata:
name: executer-api
namespace: executer
spec:
replicas: 3
selector: { matchLabels: { app: executer-api } }
strategy: { type: RollingUpdate, rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } }
template:
metadata: { labels: { app: executer-api } }
spec:
containers:
- name: backend
image: REGISTRY/executer-backend:VERSION
envFrom:
- configMapRef: { name: executer-config }
- secretRef: { name: executer-secrets }
env:
# Web/API replicas never run the scheduler — the worker owns it.
- { name: SCHEDULE_WORKER, value: '0' }
ports: [{ containerPort: 8080 }]
volumeMounts: [{ name: keyring, mountPath: /keys }]
readinessProbe:
httpGet: { path: /api/ready, port: 8080 }
initialDelaySeconds: 10
periodSeconds: 10
livenessProbe:
httpGet: { path: /api/health, port: 8080 }
initialDelaySeconds: 20
periodSeconds: 20
volumes:
- name: keyring
persistentVolumeClaim: { claimName: executer-keyring }
---
apiVersion: v1
kind: Service
metadata: { name: executer-api, namespace: executer }
spec:
selector: { app: executer-api }
ports: [{ port: 8080, targetPort: 8080 }]
---
# Exactly one scheduler owner (do not scale past 1).
apiVersion: apps/v1
kind: Deployment
metadata:
name: executer-worker
namespace: executer
spec:
replicas: 1
strategy: { type: Recreate }
selector: { matchLabels: { app: executer-worker } }
template:
metadata: { labels: { app: executer-worker } }
spec:
containers:
- name: backend
image: REGISTRY/executer-backend:VERSION
envFrom:
- configMapRef: { name: executer-config }
- secretRef: { name: executer-secrets }
env:
- { name: SCHEDULE_WORKER, value: '1' }
volumeMounts: [{ name: keyring, mountPath: /keys }]
volumes:
- name: keyring
persistentVolumeClaim: { claimName: executer-keyring }
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: executer-web
namespace: executer
spec:
replicas: 2
selector: { matchLabels: { app: executer-web } }
strategy: { type: RollingUpdate, rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } }
template:
metadata: { labels: { app: executer-web } }
spec:
containers:
- name: webui
image: REGISTRY/executer-webui:VERSION
env:
- { name: PORT, value: '3000' }
- { name: NODE_ENV, value: 'production' }
- name: ORIGIN
valueFrom: { configMapKeyRef: { name: executer-config, key: PUBLIC_SERVER_URL } }
ports: [{ containerPort: 3000 }]
---
apiVersion: v1
kind: Service
metadata: { name: executer-web, namespace: executer }
spec:
selector: { app: executer-web }
ports: [{ port: 3000, targetPort: 3000 }]
---
# Optional: scale API on load. WebUI can take an HPA too.
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: executer-api, namespace: executer }
spec:
scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: executer-api }
minReplicas: 3
maxReplicas: 10
metrics:
- type: Resource
resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } }
+39
View File
@@ -0,0 +1,39 @@
#=============================================================================
# ExecuteR - Kubernetes: single-DNS ingress
# / -> WebUI
# /api/* -> backend
# /messaging/agent -> NATS WebSocket
# /messaging/browser -> NATS WebSocket
# nginx-ingress annotations shown; adapt for your controller. cert-manager
# issues the public certificate (ExecuteR itself needs no TLS behind this).
#=============================================================================
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: executer
namespace: executer
annotations:
cert-manager.io/cluster-issuer: 'letsencrypt'
nginx.ingress.kubernetes.io/proxy-read-timeout: '3600'
nginx.ingress.kubernetes.io/proxy-send-timeout: '3600'
# Preserve the WebSocket upgrade for /messaging/*.
nginx.ingress.kubernetes.io/proxy-http-version: '1.1'
nginx.ingress.kubernetes.io/proxy-body-size: '0'
spec:
ingressClassName: nginx
tls:
- hosts: ['control.example.com']
secretName: executer-tls
rules:
- host: control.example.com
http:
paths:
- path: /messaging
pathType: Prefix
backend: { service: { name: executer-nats, port: { number: 9222 } } }
- path: /api
pathType: Prefix
backend: { service: { name: executer-api, port: { number: 8080 } } }
- path: /
pathType: Prefix
backend: { service: { name: executer-web, port: { number: 3000 } } }
+51
View File
@@ -0,0 +1,51 @@
# Kubernetes
Many nodes, autoscaling, rolling updates, cloud or multi-cloud.
```bash
# Fill in secrets, the RWX StorageClass, the ingress host, and the image refs
# (REGISTRY/VERSION) first — then:
kubectl apply -f IaC/k8s/00-namespace-config.yaml
kubectl apply -f IaC/k8s/10-data.yaml
kubectl apply -f IaC/k8s/20-executer.yaml
kubectl apply -f IaC/k8s/30-ingress.yaml
```
Manifests:
- `00-namespace-config.yaml` — namespace, ConfigMap, Secret template, and the
**ReadWriteMany** PVC for the shared Data Protection key ring.
- `10-data.yaml` — Postgres StatefulSet + a 3-node NATS JetStream cluster
(headless service for peer discovery). For production NATS, the official
Helm chart is a good alternative.
- `20-executer.yaml` — `executer-api` Deployment (replicas, `SCHEDULE_WORKER=0`,
HPA), the single `executer-worker` Deployment (`SCHEDULE_WORKER=1`,
`Recreate` so only one scheduler ever runs), and `executer-web`.
- `30-ingress.yaml` — one host routing `/`, `/api/*`, `/messaging/*` with
WebSocket-friendly timeouts and cert-manager TLS.
## The load-bearing invariants
- **`executer-keyring` PVC must be ReadWriteMany** — every API and worker pod
shares the Data Protection key ring. Set `storageClassName` to a RWX class
(CephFS/MicroCeph, NFS). With ReadWriteOnce, replicas on other nodes fail
to read cookies/CSRF/secret blobs.
- **`executer-worker` stays at replicas: 1** with `strategy: Recreate` — it is
the sole schedule owner. The API pods run `SCHEDULE_WORKER=0`.
- **Postgres** is the shared store; swap in a managed database by editing the
ConfigMap connection string and deleting the `executer-db` StatefulSet.
- Backend ingest uses a NATS queue group, so API replicas share message
processing rather than duplicating it.
## Multi-cloud / overlay / discovery
- Span clusters with a NATS **supercluster** (gateways between per-region
clusters); keep each region on its own ingress host or GeoDNS.
- A WireGuard mesh (Tailscale / NetBird) carries cross-cluster NATS gateway
and DB traffic privately — expose only the ingress publicly.
- In-cluster discovery is Kubernetes DNS (`executer-nats.executer.svc`); the
NATS StatefulSet uses stable pod DNS for cluster routes.
> Environment-specific bits (StorageClass, ingress controller/annotations,
> image registry, secrets management) must be set for your cluster. Validate
> with `kubectl apply --dry-run=server` against a staging cluster.
+55
View File
@@ -0,0 +1,55 @@
# Swarm (replicated)
Multi-node deployment with replicas behind a single VIP.
```bash
# 1. Label the node that pins Postgres storage
docker node update --label-add executer.db=true <node>
# 2. Generate NATS account keys once (any host with the backend image):
docker run --rm -v "$PWD/nats:/out" <registry>/executer-backend:latest \
nats-auth init --output /out
# -> NATS_ACCOUNT_SIGNING_SEED = account-signing.nk, NATS_ACCOUNT_PUBLIC_KEY = account.pub
# 3. Deploy
export REGISTRY=... VERSION=... POSTGRES_PASSWORD=... \
NATS_ACCOUNT_SIGNING_SEED=... NATS_ACCOUNT_PUBLIC_KEY=... \
PUBLIC_SERVER_URL=https://control.example.com
docker stack deploy -c executer-stack.yml executer
```
Then scale:
```bash
docker service scale executer_API=5 executer_WEB=3
```
## What makes this multi-instance-safe
- **`API` replicas** run `SCHEDULE_WORKER=0`; the single **`WORKER`** replica
runs `SCHEDULE_WORKER=1`. Keep `WORKER` at replicas: 1 — it owns the
scheduler. Everything else scales freely.
- **Shared key ring**: every `API` and `WORKER` task bind-mounts
`${STACK_BINDMOUNTROOT}/${STACK_NAME}/API/Keys`. On a multi-node swarm
`STACK_BINDMOUNTROOT` **must** be shared storage mounted at the same path
on every node (CephFS/MicroCeph, NFS) — a node-local path only works on a
single node. The same applies to the Postgres and JetStream bind mounts.
- **Postgres** backs all backends. Pin it to a node with `executer.db=true`
and durable storage, or point `DATABASE_CONNECTION_STRING` at a managed
database and drop the `DB` service.
- **NATS** is a 3-node JetStream cluster; `--routes nats://tasks.NATS:6222`
discovers peers via Swarm task DNS. For HA, create streams with R3
(`--replicas 3`).
## Multi-site / multi-cloud
Join nodes across sites over a WireGuard overlay (Tailscale / NetBird) so
the overlay network, NATS cluster routes and Postgres traffic stay private.
For separate regions, run a NATS **supercluster**: one cluster per region
plus gateway connections between them, and keep each region's edge on its
own DNS name (or GeoDNS to the nearest).
> These manifests are authored to the stack conventions and known Swarm
> semantics but are environment-specific (storage driver, node labels, cert
> edge). Validate with `docker stack config -c executer-stack.yml` and a
> staging swarm before production.
+130
View File
@@ -0,0 +1,130 @@
#=============================================================================
# ExecuteR - Docker Swarm stack (replicated, single VIP)
# docker stack deploy -c IaC/swarm/executer-stack.yml executer
#
# Differences from IaC/compose (single host):
# - No container_name (Swarm names replicas); scale via deploy.replicas.
# - Postgres shared DB (SQLite cannot back multiple backends).
# - Data Protection key ring on a SHARED volume (all backends read it) —
# back the `keyring` volume with CephFS/MicroCeph or NFS across nodes.
# - Web/API replicas run SCHEDULE_WORKER=0; one `worker` replica runs the
# scheduler (SCHEDULE_WORKER=1) so schedules fire once.
# - Backend ingest uses a NATS queue group, so replicas share the load.
# - NATS is a 3-node JetStream cluster (routes via tasks.NATS DNS).
#
# Fill the ${...} values in an env file or `docker stack deploy` environment.
# Put a TLS edge (Networking and TLS wiki) in front of the WEB/API published
# ports on one DNS name.
#=============================================================================
version: '3.9'
networks:
EXECUTER-EXTERNAL:
driver: overlay
attachable: true
EXECUTER-INTERNAL:
driver: overlay
internal: true
attachable: true
# Bind mounts under STACK_BINDMOUNTROOT (per the stack conventions). For a
# multi-node swarm this root MUST be shared storage mounted at the same path
# on every node (CephFS/MicroCeph, NFS) — the key ring especially is read by
# every API/WORKER task wherever it lands.
services:
DB:
image: 'postgres:17-alpine'
networks: [EXECUTER-INTERNAL]
environment:
POSTGRES_DB: executer
POSTGRES_USER: executer
POSTGRES_PASSWORD: '${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}'
volumes:
- '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/DB/Data:/var/lib/postgresql/data:rw'
deploy:
replicas: 1
placement:
constraints: ['node.labels.executer.db == true']
restart_policy: { condition: any }
NATS:
image: 'nats:2-alpine'
networks: [EXECUTER-INTERNAL]
# 3-node JetStream cluster: peers discover each other via the Swarm task
# DNS (tasks.NATS). Unique server names come from the container hostname.
command:
- '--name=${HOSTNAME}'
- '--jetstream'
- '--store_dir=/data'
- '--cluster_name=executer'
- '--cluster=nats://0.0.0.0:6222'
- '--routes=nats://tasks.NATS:6222'
- '--http_port=8222'
volumes:
- '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/NATS/JetStream:/data:rw'
deploy:
replicas: 3
restart_policy: { condition: any }
# endpoint_mode dnsrr so tasks.NATS returns every node for routing.
endpoint_mode: dnsrr
API:
image: '${REGISTRY:?set REGISTRY}/executer-backend:${VERSION:-latest}'
networks: [EXECUTER-EXTERNAL, EXECUTER-INTERNAL]
ports:
- '${BACKEND_PORT:-19080}:8080'
environment:
ASPNETCORE_URLS: 'http://0.0.0.0:8080'
DATABASE_PROVIDER: 'postgres'
DATABASE_CONNECTION_STRING: 'Host=DB;Database=executer;Username=executer;Password=${POSTGRES_PASSWORD}'
DATAPROTECTION_PATH: '/keys'
NATS_URL: 'nats://NATS:4222'
NATS_WS_PROXY: 'ws://NATS:9222'
NATS_MONITOR_URL: 'http://NATS:8222'
NATS_ACCOUNT_SIGNING_SEED: '${NATS_ACCOUNT_SIGNING_SEED:?}'
NATS_ACCOUNT_PUBLIC_KEY: '${NATS_ACCOUNT_PUBLIC_KEY:?}'
INITIAL_ADMIN_USERNAME: '${INITIAL_ADMIN_USERNAME:-admin}'
INITIAL_ADMIN_PASSWORD: '${INITIAL_ADMIN_PASSWORD:-admin}'
TRUST_PROXY: '1'
# The scheduler runs only on the dedicated worker below.
SCHEDULE_WORKER: '0'
volumes:
- '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/API/Keys:/keys:rw'
deploy:
replicas: ${API_REPLICAS:-3}
restart_policy: { condition: any }
update_config: { order: start-first, parallelism: 1 }
WORKER:
image: '${REGISTRY:?set REGISTRY}/executer-backend:${VERSION:-latest}'
networks: [EXECUTER-INTERNAL]
environment:
ASPNETCORE_URLS: 'http://0.0.0.0:8080'
DATABASE_PROVIDER: 'postgres'
DATABASE_CONNECTION_STRING: 'Host=DB;Database=executer;Username=executer;Password=${POSTGRES_PASSWORD}'
DATAPROTECTION_PATH: '/keys'
NATS_URL: 'nats://NATS:4222'
NATS_ACCOUNT_SIGNING_SEED: '${NATS_ACCOUNT_SIGNING_SEED:?}'
NATS_ACCOUNT_PUBLIC_KEY: '${NATS_ACCOUNT_PUBLIC_KEY:?}'
# The single scheduler owner. Keep this at exactly one replica.
SCHEDULE_WORKER: '1'
volumes:
- '${STACK_BINDMOUNTROOT:-/mnt/data/docker/stacks}/${STACK_NAME:-stk-executer-00001}/API/Keys:/keys:rw'
deploy:
replicas: 1
restart_policy: { condition: any }
WEB:
image: '${REGISTRY:?set REGISTRY}/executer-webui:${VERSION:-latest}'
networks: [EXECUTER-EXTERNAL]
ports:
- '${WEBUI_PORT:-13080}:3000'
environment:
PORT: '3000'
NODE_ENV: 'production'
ORIGIN: '${PUBLIC_SERVER_URL:-https://control.example.com}'
deploy:
replicas: ${WEB_REPLICAS:-2}
restart_policy: { condition: any }
update_config: { order: start-first, parallelism: 1 }
+38 -20
View File
@@ -230,7 +230,7 @@ Full script-execution, enrollment, and remote-shell sequence diagrams are in
Run the stack:
```powershell
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
docker compose -f IaC/compose/docker-compose.yml -f IaC/compose/docker-compose.dev.yml up -d --build
```
On a server, deploy straight from the repository — no clone needed. This pulls
@@ -303,9 +303,15 @@ and `secrets/nats/resolver.conf` (mounted into the NATS container).
## Docker Compose
Services follow the stack conventions: `EXTERNAL` + `INTERNAL` bridge networks,
container names `EXECUTER-{NATS,API,WEB}-00001`, service-name networking, and
uncommon host ports.
Deployment manifests live under **[IaC/](IaC/)**: `IaC/compose` (single-host
Docker Compose), `IaC/swarm` (multi-node Docker Swarm with replicas), and
`IaC/k8s` (Kubernetes). All three follow the stack conventions and share the
same images; see the [scaling wiki](../../wiki/Scaling-and-HA) for when to
use each.
The Compose stack uses `EXTERNAL` + `INTERNAL` bridge networks, container
names `EXECUTER-{NATS,API,WEB}-00001`, service-name networking, and uncommon
host ports.
| Service | Container | Host port | Internal |
|---------|-----------|-----------|----------|
@@ -317,7 +323,9 @@ Volumes bind under `${STACK_BINDMOUNTROOT}/${STACK_NAME}/{Tier}/Data`. The NATS
image is pinned by digest. See `.env.example` for every variable.
```powershell
docker compose up -d --build
# from the repository root
docker compose -f IaC/compose/docker-compose.yml up -d --build
# ...or just: ./scripts/deploy.sh
```
---
@@ -363,8 +371,17 @@ The finish page offers to **open the console in the browser** (checked by
default) — a wildcard bind (`0.0.0.0` / `::`) opens `http://localhost:<port>`,
a specific bind address opens that address directly.
Upgrades never overwrite existing configuration, and uninstall stops and
removes the service. The MSI installs exactly one instance — multi-instance
boxes use the ZIP with distinct ports and service names.
removes the service. By default a plain uninstall **keeps** the generated
data, sign-in and self-signed chain so a reinstall resumes where it left
off (the managed chain is located in the machine certificate stores by
subject and reused when still valid). For a fully clean removal, tick
**Also remove all data, keys and self-signed certificates** on the
uninstall page — or pass `PURGEDATA=1` to a silent uninstall. That deletes
`appsettings.json`, `data`, `logs` and `secrets` and removes the
self-signed root/intermediate/leaf from the Windows stores. The same
cleanup is available directly as `ExecuteR-Server.exe purge`. The MSI
installs exactly one instance — multi-instance boxes use the ZIP with
distinct ports and service names.
Bundles ship the **agent installers** (`agent-package/` with `Agent.msi`,
`Agent.zip`, the unix zips and `VERSION`), so the URL install command works
@@ -448,19 +465,20 @@ Caddy / Nginx UI / nginx can bind or trust the files directly and stay
current. On **Linux/macOS/containers** the PEM files are the primary store
(`TLS_CERT_DIR` overrides; keep it on a persisted volume in containers).
**Agents** skip verification only when the operator says so — a
self-signed server that later gains a proxy with a real certificate must
not leave agents skipping validation needlessly. The Add-Device modal (and
the Settings token panel) carry a **Skip TLS verification** checkbox,
pre-selected only while the server is serving its self-signed chain
directly; when ticked, the one-liner and the served install script include
the skip bits and set the agent's `TlsSkipVerify` registry value
(`/etc/executer/agent.json` on unix) — still fully encrypted. The value is
GPO-manageable (`Skip TLS certificate verification` in the ADMX template,
policy key beats local config), `configure --skip-tls-verify` sets it by
hand, and the agent MSI wizard has a matching checkbox — unchecked by
default (`SKIPTLSVERIFY=1` silently). Left unticked, agents validate
normally.
**Agents trust a direct self-signed server automatically — without pinning.**
When the server serves its chain directly, the Add-Device modal (and
Settings token panel) pre-select **Trust self-signed certificate**, which
sets `ServerCaAutoInstall`. The agent then fetches the CA from
`/api/enrollment/ca` and **installs it into the OS trust store**, and a
background service keeps it current as the server rotates its chain — so
ordinary system validation trusts the server and renewals never lapse. It
is deliberately *not* pinned or forced: if a reverse proxy with a real
certificate is added later, that certificate validates normally and the
installed self-signed CA simply goes unused — nothing to break. The setting
is GPO-manageable (ADMX `Install the server's self-signed CA`),
`configure --install-server-ca` sets it by hand, and the agent MSI accepts
`CAINSTALL=1`. For an accept-any escape hatch (no validation), `insecure` /
`TlsSkipVerify=1` remains.
---
+10 -7
View File
@@ -71,9 +71,10 @@ command -v curl >/dev/null 2>&1 || die "curl is required"
docker info >/dev/null 2>&1 || die "cannot talk to the Docker daemon (need root or docker group?)"
# ── Locate or fetch the stack files ─────────────────────────────────────────
COMPOSE_REL="IaC/compose"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd || echo '')"
REPO_ROOT=""
if [[ -n "$SCRIPT_DIR" && -f "$SCRIPT_DIR/../docker-compose.yml" ]]; then
if [[ -n "$SCRIPT_DIR" && -f "$SCRIPT_DIR/../$COMPOSE_REL/docker-compose.yml" ]]; then
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
fi
@@ -94,12 +95,12 @@ else
fi
}
fetch docker-compose.yml || die "docker-compose.yml is required"
fetch "$COMPOSE_REL/docker-compose.yml" || die "docker-compose.yml is required"
fetch .env.example || die ".env.example is required"
fetch src/Infra/nats/nats.conf || die "nats.conf is required"
[[ $WITH_PROXY -eq 1 ]] && { fetch docker-compose.proxy.yml; fetch src/Infra/nginx/executer.conf; }
[[ $WITH_PROXY -eq 1 ]] && { fetch "$COMPOSE_REL/docker-compose.proxy.yml"; fetch src/Infra/nginx/executer.conf; }
# Optional; only needed when building from source.
fetch docker-compose.dev.yml || true
fetch "$COMPOSE_REL/docker-compose.dev.yml" || true
fi
cd "$STACK_DIR"
@@ -134,10 +135,12 @@ mkdir -p \
"$STACK_BINDMOUNTROOT/$STACK_NAME/Proxy/Acme"
# ── Compose file selection ──────────────────────────────────────────────────
COMPOSE_FILES=(-f docker-compose.yml)
# Compose files live in IaC/compose; their relative build/mount paths are
# authored against that location, so they run correctly from the stack root.
COMPOSE_FILES=(-f "$COMPOSE_REL/docker-compose.yml")
if [[ $WITH_PROXY -eq 1 ]]; then
[[ -f docker-compose.proxy.yml ]] || die "--with-proxy needs docker-compose.proxy.yml"
COMPOSE_FILES+=(-f docker-compose.proxy.yml)
[[ -f "$COMPOSE_REL/docker-compose.proxy.yml" ]] || die "--with-proxy needs $COMPOSE_REL/docker-compose.proxy.yml"
COMPOSE_FILES+=(-f "$COMPOSE_REL/docker-compose.proxy.yml")
fi
compose() { docker compose "${COMPOSE_FILES[@]}" "$@"; }
+13 -4
View File
@@ -134,10 +134,11 @@ public static class AgentCli
}
}
var installServerCa = args.Contains("--install-server-ca");
var skipTlsVerify = args.Contains("--skip-tls-verify");
if (url is null && token is null && proxy is null && !skipTlsVerify)
if (url is null && token is null && proxy is null && !installServerCa && !skipTlsVerify)
{
Console.Error.WriteLine("Usage: configure --url <server-url> [--token <bootstrap-token>] [--proxy <proxy-url>] [--skip-tls-verify]");
Console.Error.WriteLine("Usage: configure --url <server-url> [--token <bootstrap-token>] [--proxy <proxy-url>] [--install-server-ca] [--skip-tls-verify]");
return 1;
}
@@ -159,10 +160,18 @@ public static class AgentCli
registry.WriteString(Branding.AgentRegistryKey, Agent.Configuration.AgentConfigurationKeys.ProxyUrl, proxy);
}
if (installServerCa)
{
// Install the server's self-signed CA into the OS trust store (and
// keep it current) so system validation trusts a direct/local
// connection. Not pinning — a real cert behind a proxy still works.
registry.WriteDword(Branding.AgentRegistryKey, Agent.Configuration.AgentConfigurationKeys.ServerCaAutoInstall, 1);
}
if (skipTlsVerify)
{
// For servers on the managed self-signed chain without a proxy:
// the connection stays TLS-encrypted, validation is skipped.
// Escape hatch: accept any certificate (still encrypted). Prefer
// --install-server-ca for self-signed servers.
registry.WriteDword(Branding.AgentRegistryKey, Agent.Configuration.AgentConfigurationKeys.TlsSkipVerify, 1);
}
@@ -21,6 +21,14 @@ public sealed class AgentConfiguration
public required ConfigurationValue<bool> TlsSkipVerify { get; init; }
public required ConfigurationValue<string?> ProxyUrl { get; init; }
/// <summary>
/// Install the server's managed self-signed CA into the OS trust store so
/// ordinary system validation succeeds on a direct/local connection. Not
/// pinning and not forced — a later reverse proxy with a real certificate
/// still validates normally and the self-signed CA just goes unused.
/// </summary>
public ConfigurationValue<bool> ServerCaAutoInstall { get; init; } = new(false, ConfigurationSource.Default);
/// <summary>Parsed ServerURL; null when unset or invalid.</summary>
public ServerUrl? ServerUrl =>
Shared.Infrastructure.Routing.ServerUrl.TryParse(ServerUrlText.Value, out var parsed, out _) ? parsed : null;
@@ -50,6 +58,7 @@ public sealed class AgentConfigurationLoader(IRegistryStore registry, bool allow
AllowScriptExecution = ResolveBool(AgentConfigurationKeys.AllowScriptExecution, defaultValue: true),
TlsSkipVerify = ResolveBool(AgentConfigurationKeys.TlsSkipVerify, defaultValue: false),
ProxyUrl = ResolveString(AgentConfigurationKeys.ProxyUrl, AgentConfigurationKeys.EnvironmentNames.ProxyUrl, null),
ServerCaAutoInstall = ResolveBool(AgentConfigurationKeys.ServerCaAutoInstall, defaultValue: false),
};
}
@@ -20,6 +20,14 @@ public static class AgentConfigurationKeys
/// </summary>
public const string TlsSkipVerify = "TlsSkipVerify";
/// <summary>
/// DWORD 1: fetch the server's managed self-signed CA and install it into
/// the OS trust store (and keep it current across renewals) so system
/// validation trusts a direct/local self-signed server. Not pinning —
/// a proxy with a real certificate added later still validates normally.
/// </summary>
public const string ServerCaAutoInstall = "ServerCaAutoInstall";
/// <summary>
/// Explicit outbound proxy URL (http://proxy:8080). Unset, the agent
/// honors the system/environment proxy; either way it authenticates to
+10 -2
View File
@@ -80,8 +80,16 @@ public sealed class EnrollmentService(
AgentVersion: BuildVersion.Resolve(typeof(EnrollmentService).Assembly),
Device: ReadDeviceInfo());
// TlsSkipVerify (registry/GPO): servers on the managed self-signed
// chain without a proxy — the connection stays TLS-encrypted.
// Self-signed servers: make the CA available to the OS trust store
// first so ordinary system validation succeeds here — not pinned, so
// a proxy with a real certificate added later still validates.
if (configuration.ServerCaAutoInstall.Value)
{
await ServerTrust.FetchAndInstallCaAsync(serverUrl, HttpClient.DefaultProxy, logger, cancellationToken);
}
// TlsSkipVerify is the accept-any escape hatch; otherwise validate
// against the OS trust store (which now contains the CA above).
using var handler = new HttpClientHandler();
if (configuration.TlsSkipVerify.Value)
{
+179
View File
@@ -0,0 +1,179 @@
using System.Diagnostics;
using System.Net;
using System.Runtime.Versioning;
using System.Security.Cryptography.X509Certificates;
using Microsoft.Extensions.Logging;
using Shared.Contracts.Api;
using Shared.Infrastructure.Routing;
namespace Agent.Enrollment;
/// <summary>
/// Makes the server's managed self-signed CA available to the OS trust store
/// so ordinary system validation succeeds when the agent connects to the
/// self-signed server directly (e.g. a local URL). It is intentionally NOT
/// pinned or forced: if a reverse proxy with a real certificate is added
/// later, system validation trusts that instead, and the installed
/// self-signed CA simply goes unused — nothing to break. Certs come from
/// GET /api/enrollment/ca; a 404 means the server is not self-signed.
/// </summary>
public static class ServerTrust
{
/// <summary>
/// Fetches the server's CA chain and installs it into the OS trust store
/// (idempotent, best-effort). The fetch accepts any certificate — it is
/// retrieving public CA certs to establish trust — then verifies the
/// payload is real PEM certificates before installing. Returns true when
/// a chain was fetched.
/// </summary>
public static async Task<bool> FetchAndInstallCaAsync(
ServerUrl serverUrl, IWebProxy? proxy, ILogger logger, CancellationToken cancellationToken)
{
using var handler = new HttpClientHandler
{
ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
};
if (proxy is not null)
{
handler.Proxy = proxy;
handler.UseProxy = true;
}
using var http = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
var endpoint = serverUrl.ApiEndpoint(ApiRoutes.EnrollmentCaChain);
string pem;
X509Certificate2Collection chain = [];
try
{
using var response = await http.GetAsync(endpoint, cancellationToken);
if (response.StatusCode == HttpStatusCode.NotFound)
{
return false; // Server is not self-signed — nothing to install.
}
response.EnsureSuccessStatusCode();
pem = await response.Content.ReadAsStringAsync(cancellationToken);
chain.ImportFromPem(pem);
if (chain.Count == 0)
{
logger.LogWarning("Server CA response contained no certificates");
return false;
}
}
catch (Exception ex)
{
logger.LogWarning(ex, "Could not fetch the server CA from {Endpoint}", endpoint);
return false;
}
if (OperatingSystem.IsWindows())
{
InstallWindows(chain, logger);
}
else if (OperatingSystem.IsMacOS())
{
InstallMac(pem, logger);
}
else
{
InstallLinux(pem, logger);
}
return true;
}
[SupportedOSPlatform("windows")]
private static void InstallWindows(X509Certificate2Collection chain, ILogger logger)
{
try
{
foreach (var cert in chain)
{
var selfIssued = cert.SubjectName.RawData.AsSpan().SequenceEqual(cert.IssuerName.RawData);
using var store = new X509Store(
selfIssued ? StoreName.Root : StoreName.CertificateAuthority, StoreLocation.LocalMachine);
store.Open(OpenFlags.ReadWrite);
foreach (var stale in store.Certificates.Find(
X509FindType.FindBySubjectDistinguishedName, cert.Subject, validOnly: false))
{
if (stale.Thumbprint != cert.Thumbprint)
{
store.Remove(stale);
}
}
if (store.Certificates.Find(X509FindType.FindByThumbprint, cert.Thumbprint, validOnly: false).Count == 0)
{
store.Add(cert);
logger.LogInformation("Installed server CA into LocalMachine\\{Store}: {Subject}",
selfIssued ? "Root" : "CA", cert.Subject);
}
}
}
catch (Exception ex)
{
logger.LogWarning(ex, "Could not install the server CA into the Windows trust store");
}
}
private static void InstallLinux(string pem, ILogger logger)
{
try
{
// Debian/Ubuntu vs RHEL anchor locations.
if (Directory.Exists("/usr/local/share/ca-certificates"))
{
File.WriteAllText("/usr/local/share/ca-certificates/executer-server-ca.crt", pem);
RunBestEffort("update-ca-certificates", logger);
}
else if (Directory.Exists("/etc/pki/ca-trust/source/anchors"))
{
File.WriteAllText("/etc/pki/ca-trust/source/anchors/executer-server-ca.crt", pem);
RunBestEffort("update-ca-trust", logger);
}
else
{
logger.LogDebug("No known CA anchor directory found; skipping OS trust install");
}
}
catch (Exception ex)
{
logger.LogWarning(ex, "Could not install the server CA into the Linux trust store");
}
}
private static void InstallMac(string pem, ILogger logger)
{
try
{
var path = Path.Combine(Path.GetTempPath(), "executer-server-ca.pem");
File.WriteAllText(path, pem);
RunBestEffort("security", logger,
"add-trusted-cert", "-d", "-r", "trustRoot", "-k", "/Library/Keychains/System.keychain", path);
File.Delete(path);
}
catch (Exception ex)
{
logger.LogWarning(ex, "Could not install the server CA into the macOS keychain");
}
}
private static void RunBestEffort(string file, ILogger logger, params string[] args)
{
try
{
var psi = new ProcessStartInfo(file) { RedirectStandardError = true, RedirectStandardOutput = true };
foreach (var arg in args)
{
psi.ArgumentList.Add(arg);
}
using var process = Process.Start(psi);
process?.WaitForExit(15000);
}
catch (Exception ex)
{
logger.LogDebug(ex, "Trust-store refresh command '{File}' did not run", file);
}
}
}
@@ -37,8 +37,11 @@ public static class AgentNatsOptionsFactory
LoggerFactory = loggerFactory,
};
var skipTlsVerify = configuration.TlsSkipVerify.Value;
if (skipTlsVerify)
// TlsSkipVerify accepts any cert (still encrypted); otherwise the OS
// trust store validates the wss server cert — which contains the
// self-signed CA when ServerCaAutoInstall installed it.
var skipVerify = configuration.TlsSkipVerify.Value;
if (skipVerify)
{
options = options with { TlsOpts = NatsTlsOpts.Default with { InsecureSkipVerify = true } };
}
@@ -54,9 +57,7 @@ public static class AgentNatsOptionsFactory
// HttpClient.DefaultProxy on its own.
clientOptions.Proxy = System.Net.Http.HttpClient.DefaultProxy;
// TlsSkipVerify (registry/GPO): accept the managed
// self-signed chain — the traffic stays TLS-encrypted.
if (skipTlsVerify)
if (skipVerify)
{
clientOptions.RemoteCertificateValidationCallback = (_, _, _, _) => true;
}
+2
View File
@@ -69,6 +69,8 @@ public static class AgentHost
builder.Services.AddSingleton(new AgentConfigurationLoader(registry, allowEnvironment: !runAsService));
builder.Services.AddHostedService<AgentWorker>();
// Keeps the pinned server CA current across renewals (pinned mode only).
builder.Services.AddHostedService<CaRefreshService>();
return builder.Build();
}
+45
View File
@@ -0,0 +1,45 @@
using Agent.Configuration;
using Agent.Enrollment;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
namespace Agent.Service;
/// <summary>
/// Keeps the server's self-signed CA present in the OS trust store when
/// ServerCaAutoInstall is set: installs it on start and re-installs every few
/// hours, so a server-side chain rotation stays trusted without operator
/// action. It never forces validation against the CA — a proxy with a real
/// certificate added later is unaffected. Idle otherwise.
/// </summary>
public sealed class CaRefreshService(
AgentConfigurationLoader loader, ILogger<CaRefreshService> logger) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
if (!loader.Load().ServerCaAutoInstall.Value)
{
logger.LogDebug("Server CA auto-install idle (not enabled)");
return;
}
using var timer = new PeriodicTimer(TimeSpan.FromHours(6));
try
{
do
{
var configuration = loader.Load();
if (configuration.ServerCaAutoInstall.Value && configuration.ServerUrl is { } serverUrl)
{
await ServerTrust.FetchAndInstallCaAsync(
serverUrl, System.Net.Http.HttpClient.DefaultProxy, logger, stoppingToken);
}
}
while (await timer.WaitForNextTickAsync(stoppingToken));
}
catch (OperationCanceledException)
{
// Shutdown.
}
}
}
+34 -9
View File
@@ -24,6 +24,25 @@ public static class InstallEndpoints
app.MapGet(ApiRoutes.AgentPackage, GetAgentPackage)
.RequireRateLimiting(RateLimitPolicies.Enrollment)
.AllowAnonymous();
app.MapGet(ApiRoutes.EnrollmentCaChain, GetCaChain)
.RequireRateLimiting(RateLimitPolicies.Enrollment)
.AllowAnonymous();
}
/// <summary>
/// Serves the managed self-signed CA chain (root + intermediate, public
/// certs only) so agents can pin it and keep validating the server across
/// renewals. 404 when the server is not running self-signed TLS — nothing
/// to distribute, agents validate against the real edge certificate.
/// </summary>
private static IResult GetCaChain(HttpContext context)
{
var manager = context.RequestServices.GetService<Backend.Tls.SelfSignedTlsManager>();
var pem = manager?.CaChainPem();
return pem is null
? Results.NotFound()
: Results.Text(pem, "application/x-pem-file; charset=utf-8");
}
private static IResult GetInstallScript(
@@ -99,17 +118,22 @@ public static class InstallEndpoints
"else { [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true } }";
// NOTE: $$""" — interpolations are {{ }}, single braces are literal PowerShell.
private static string BuildMsiScript(string baseUrl, string token, string packageUrl, bool skipVerify) => $$"""
// selfSigned: the server serves its managed self-signed chain directly, so
// the initial download skips verification (the cert isn't trusted yet) and
// the agent is told to install the server CA into the OS trust store (and
// keep it current) — system validation then trusts the server, without
// pinning, so a proxy with a real cert added later still works.
private static string BuildMsiScript(string baseUrl, string token, string packageUrl, bool selfSigned) => $$"""
#Requires -RunAsAdministrator
$ErrorActionPreference = 'Stop'
Write-Host 'Installing ExecuteR Agent...'
{{(skipVerify ? PsSkipVerify : "")}}
{{(selfSigned ? PsSkipVerify : "")}}
$server = '{{baseUrl}}'
$token = '{{token}}'
$msi = Join-Path $env:TEMP ('ExecuteRAgent-' + [guid]::NewGuid().ToString('N') + '.msi')
try {
Invoke-WebRequest -Uri '{{packageUrl}}' -OutFile $msi -UseBasicParsing
$arguments = @('/i', ('"' + $msi + '"'), '/qn', "SERVERURL=$server", "BOOTSTRAPTOKEN=$token"{{(skipVerify ? ", 'SKIPTLSVERIFY=1'" : "")}})
$arguments = @('/i', ('"' + $msi + '"'), '/qn', "SERVERURL=$server", "BOOTSTRAPTOKEN=$token"{{(selfSigned ? ", 'CAINSTALL=1'" : "")}})
$p = Start-Process msiexec.exe -ArgumentList $arguments -Wait -PassThru
if ($p.ExitCode -ne 0) { throw "msiexec exited with $($p.ExitCode)" }
Write-Host 'ExecuteR Agent installed. It will enroll and start automatically.'
@@ -124,7 +148,7 @@ public static class InstallEndpoints
/// agent zip, unpacks to /opt/executer/agent, configures enrollment via
/// the agent's own CLI and registers the systemd unit / launchd daemon.
/// </summary>
private static string BuildUnixScript(string baseUrl, string token, string os, bool skipVerify) => $$"""
private static string BuildUnixScript(string baseUrl, string token, string os, bool selfSigned) => $$"""
#!/usr/bin/env bash
set -euo pipefail
if [ "$(id -u)" -ne 0 ]; then echo 'Run with sudo/root.' >&2; exit 1; fi
@@ -140,7 +164,7 @@ public static class InstallEndpoints
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
echo "Installing ExecuteR Agent ({{os}}-${arch})..."
curl -fsSL{{(skipVerify ? "k" : "")}} "$pkg" -o "$tmp/agent.zip"
curl -fsSL{{(selfSigned ? "k" : "")}} "$pkg" -o "$tmp/agent.zip"
mkdir -p "$dest"
if command -v unzip >/dev/null 2>&1; then
unzip -oq "$tmp/agent.zip" -d "$dest"
@@ -148,16 +172,17 @@ public static class InstallEndpoints
python3 -m zipfile -e "$tmp/agent.zip" "$dest"
fi
chmod +x "$dest/executer-agent"
"$dest/executer-agent" configure --url "$server" --token "$token"{{(skipVerify ? " --skip-tls-verify" : "")}}
{{(selfSigned ? "# Trust the server's managed self-signed CA for host tooling too.\n curl -fsSLk \"" + baseUrl + ApiRoutes.EnrollmentCaChain + "\" -o /tmp/executer-ca.pem 2>/dev/null && {\n if [ -d /usr/local/share/ca-certificates ]; then cp /tmp/executer-ca.pem /usr/local/share/ca-certificates/executer-ca.crt && update-ca-certificates >/dev/null 2>&1 || true;\n elif [ -d /etc/pki/ca-trust/source/anchors ]; then cp /tmp/executer-ca.pem /etc/pki/ca-trust/source/anchors/executer-ca.crt && update-ca-trust >/dev/null 2>&1 || true; fi; rm -f /tmp/executer-ca.pem; }" : "")}}
"$dest/executer-agent" configure --url "$server" --token "$token"{{(selfSigned ? " --install-server-ca" : "")}}
"$dest/executer-agent" initialize
echo 'ExecuteR Agent installed. It will enroll and start automatically.'
""";
private static string BuildZipScript(string baseUrl, string token, string packageUrl, bool skipVerify) => $$"""
private static string BuildZipScript(string baseUrl, string token, string packageUrl, bool selfSigned) => $$"""
#Requires -RunAsAdministrator
$ErrorActionPreference = 'Stop'
Write-Host 'Installing ExecuteR Agent (portable)...'
{{(skipVerify ? PsSkipVerify : "")}}
{{(selfSigned ? PsSkipVerify : "")}}
$server = '{{baseUrl}}'
$token = '{{token}}'
$dest = Join-Path $env:ProgramFiles 'ExecuteR\Agent'
@@ -171,7 +196,7 @@ public static class InstallEndpoints
New-Item -Path 'HKLM:\SOFTWARE\ExecuteR' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\SOFTWARE\ExecuteR' -Name 'ServerURL' -Value $server
Set-ItemProperty -Path 'HKLM:\SOFTWARE\ExecuteR' -Name 'BootstrapToken' -Value $token
{{(skipVerify ? "Set-ItemProperty -Path 'HKLM:\\SOFTWARE\\ExecuteR' -Name 'TlsSkipVerify' -Value 1 -Type DWord" : "")}}
{{(selfSigned ? "Set-ItemProperty -Path 'HKLM:\\SOFTWARE\\ExecuteR' -Name 'ServerCaAutoInstall' -Value 1 -Type DWord" : "")}}
& $exe initialize
Write-Host 'ExecuteR Agent installed and starting.'
}
+10 -5
View File
@@ -26,6 +26,11 @@ public sealed class MessagingWorkers(
{
private readonly Dictionary<string, DeviceStatus> lastKnownStatus = [];
// Core NATS queue group: with multiple backend replicas, NATS delivers
// each presence/inventory/output/progress message to exactly one member,
// so ingest is load-balanced instead of every replica writing duplicates.
private const string WorkerQueueGroup = "executer-backend-workers";
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
if (!hub.IsConfigured)
@@ -73,7 +78,7 @@ public sealed class MessagingWorkers(
private async Task ConsumePresenceAsync(CancellationToken cancellationToken)
{
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllAgentPresence, cancellationToken: cancellationToken))
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllAgentPresence, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken))
{
var payload = Parse<PresencePayload>(msg.Data);
if (payload is null || !SubjectIdentifier.IsValid(payload.ClientId))
@@ -135,7 +140,7 @@ public sealed class MessagingWorkers(
private async Task ConsumeInventoryAsync(CancellationToken cancellationToken)
{
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllAgentInventory, cancellationToken: cancellationToken))
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllAgentInventory, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken))
{
var payload = Parse<InventoryPayload>(msg.Data);
var report = payload?.Report;
@@ -203,7 +208,7 @@ public sealed class MessagingWorkers(
/// </summary>
private async Task ConsumeAgentEventsAsync(CancellationToken cancellationToken)
{
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllAgentEvents, cancellationToken: cancellationToken))
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllAgentEvents, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken))
{
var payload = Parse<AgentEventPayload>(msg.Data);
if (payload is null
@@ -233,7 +238,7 @@ public sealed class MessagingWorkers(
private async Task ConsumeJobOutputAsync(CancellationToken cancellationToken)
{
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllJobOutput, cancellationToken: cancellationToken))
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllJobOutput, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken))
{
var payload = Parse<JobOutputPayload>(msg.Data);
if (payload is null)
@@ -277,7 +282,7 @@ public sealed class MessagingWorkers(
private async Task ConsumeJobProgressAsync(CancellationToken cancellationToken)
{
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllJobProgress, cancellationToken: cancellationToken))
await foreach (var msg in hub.Require().SubscribeAsync<byte[]>(NatsSubjects.AllJobProgress, queueGroup: WorkerQueueGroup, cancellationToken: cancellationToken))
{
var payload = Parse<JobProgressPayload>(msg.Data);
if (payload is null)
+7
View File
@@ -53,6 +53,13 @@ if (args.Length > 0 && args[0] == "service")
return Backend.Standalone.ServerCli.RunService(args[1..]);
}
// CLI mode: clean-uninstall — forget the self-signed chain and delete
// generated runtime state (invoked by the MSI when PURGEDATA=1).
if (args.Length > 0 && args[0] == "purge")
{
return Backend.Standalone.ServerCli.RunPurge(args[1..]);
}
// Standalone bundle: when setup generated an appsettings.json next to the
// binary, anchor the content root there so the server behaves identically
// however it is launched (console from any directory, SCM, systemd).
+73
View File
@@ -14,6 +14,7 @@ namespace Backend.Standalone;
/// downloading nats-server for this platform if absent
/// service install — register as a Windows service / systemd unit
/// service uninstall — stop and remove the service
/// purge [--yes] — remove the self-signed chain + generated state
///
/// The same binary is the server: running it with no arguments starts the
/// control plane (UI + API + WebSocket relay + optional NATS sidecar).
@@ -362,6 +363,78 @@ public static class ServerCli
};
}
/// <summary>
/// Clean-uninstall: forget the managed self-signed chain from the Windows
/// certificate stores and delete the runtime state `setup` generated
/// (appsettings.json, data, logs, secrets, nats.conf). MSI-owned files
/// (the binary, wwwroot, nats-server, agent-package) are left for the
/// installer to remove. Interactive callers are prompted unless --yes.
/// </summary>
public static int RunPurge(string[] args)
{
var assumeYes = args.Contains("--yes") || args.Contains("-y");
if (!assumeYes)
{
Console.Write("Remove all ExecuteR data, keys and self-signed certificates? [y/N] ");
var answer = Console.ReadLine()?.Trim();
if (answer is not ("y" or "Y" or "yes" or "YES"))
{
Console.WriteLine("Purge cancelled.");
return 0;
}
}
var removed = Backend.Tls.TlsCleanup.RemoveWindowsChain();
if (removed > 0)
{
Console.WriteLine($"Removed {removed} self-signed certificate(s) from the machine stores.");
}
var baseDir = AppContext.BaseDirectory;
foreach (var dir in new[] { "data", "logs", "secrets" })
{
DeleteDirectory(Path.Combine(baseDir, dir));
}
foreach (var file in new[] { "appsettings.json", Path.Combine("nats", "nats.conf") })
{
var path = Path.Combine(baseDir, file);
if (File.Exists(path))
{
try
{
File.Delete(path);
Console.WriteLine($"Deleted {path}");
}
catch (Exception ex)
{
Console.Error.WriteLine($"Could not delete {path}: {ex.Message}");
}
}
}
Console.WriteLine("Purge complete.");
return 0;
}
private static void DeleteDirectory(string path)
{
if (!Directory.Exists(path))
{
return;
}
try
{
Directory.Delete(path, recursive: true);
Console.WriteLine($"Deleted {path}");
}
catch (Exception ex)
{
Console.Error.WriteLine($"Could not delete {path}: {ex.Message}");
}
}
private static int InstallWindows(string exe, string name)
{
// Idempotent: create may fail when the service exists (repair or MSI
+20
View File
@@ -60,6 +60,26 @@ public sealed class SelfSignedTlsManager
/// <summary>The current server certificate; null until the first EnsureChain.</summary>
public X509Certificate2? ServerCertificate => Volatile.Read(ref leaf);
/// <summary>
/// The public CA chain (intermediate then root) as PEM, for distribution
/// to agents so they can validate the leaf and keep trusting it across
/// renewals. Null before the chain exists. Contains no private keys.
/// </summary>
public string? CaChainPem()
{
lock (gate)
{
var root = persistence.Load(TlsRole.Root);
var intermediate = persistence.Load(TlsRole.Intermediate);
if (root is null || intermediate is null)
{
return null;
}
return intermediate.ExportCertificatePem() + '\n' + root.ExportCertificatePem() + '\n';
}
}
/// <summary>
/// Creates or re-issues whatever links are missing, expiring, or no
/// longer signed by the current parent (a rotated root cascades down).
+17
View File
@@ -0,0 +1,17 @@
using System.Runtime.Versioning;
namespace Backend.Tls;
/// <summary>Clean-uninstall helper: forget the managed self-signed chain.</summary>
public static class TlsCleanup
{
/// <summary>
/// Removes the managed self-signed chain from the Windows machine
/// certificate stores. No-op off Windows. Returns the count removed.
/// </summary>
public static int RemoveWindowsChain()
=> OperatingSystem.IsWindows() ? RemoveWindowsChainCore() : 0;
[SupportedOSPlatform("windows")]
private static int RemoveWindowsChainCore() => WindowsStoreTlsPersistence.RemoveManagedChain();
}
+30
View File
@@ -193,6 +193,36 @@ internal sealed class WindowsStoreTlsPersistence(string mirrorDirectory) : ITlsP
return persisted;
}
/// <summary>
/// Removes the managed self-signed chain (by subject) from all three
/// machine stores — the clean-uninstall counterpart to Save. Returns the
/// number of certificates removed; best-effort per store.
/// </summary>
public static int RemoveManagedChain()
{
var removed = 0;
foreach (var role in new[] { TlsRole.Root, TlsRole.Intermediate, TlsRole.Leaf })
{
try
{
using var store = new X509Store(StoreFor(role), StoreLocation.LocalMachine);
store.Open(OpenFlags.ReadWrite);
foreach (var existing in store.Certificates.Find(
X509FindType.FindBySubjectDistinguishedName, TlsSubjects.For(role), validOnly: false))
{
store.Remove(existing);
removed++;
}
}
catch (Exception)
{
// Best effort — a locked or missing store must not fail uninstall.
}
}
return removed;
}
public void Complete(X509Certificate2 root, X509Certificate2 intermediate, X509Certificate2 leaf)
{
// SChannel serves the chain from the stores; the PEM mirror exists
+193 -7
View File
@@ -43,6 +43,7 @@ public sealed class TlsSettings
public static TlsSettings FromConfiguration(IConfiguration configuration)
{
var enabled = configuration["TLS_SELF_SIGNED"] != "0";
var certDir = configuration["TLS_CERT_DIR"];
var dataDir = Path.GetDirectoryName(Path.GetFullPath(
configuration["DATABASE_PATH"] is { Length: > 0 } db ? db : "data/app.db")) ?? "data";
@@ -50,19 +51,21 @@ public sealed class TlsSettings
var dnsNames = new List<string> { "localhost" };
var ipAddresses = new List<IPAddress> { IPAddress.Loopback, IPAddress.IPv6Loopback };
// Verification is off at the proxy, so the SAN set only needs to be
// friendly for direct browsing: hostname, FQDN and the bind address.
// Cover every way this host is reachable directly: the hostname, the
// hostname under each adapter's connection-specific DNS suffix, the
// resolved FQDN, every IP on every adapter, plus localhost/loopback.
string? hostName = null;
try
{
var host = Dns.GetHostName();
AddDns(dnsNames, host);
hostName = Dns.GetHostName();
AddDns(dnsNames, hostName);
try
{
AddDns(dnsNames, Dns.GetHostEntry(host).HostName);
AddDns(dnsNames, Dns.GetHostEntry(hostName).HostName);
}
catch (Exception)
{
// No resolvable FQDN — hostname and localhost suffice.
// No resolvable FQDN — hostname and suffix-derived names suffice.
}
}
catch (Exception)
@@ -70,6 +73,35 @@ public sealed class TlsSettings
// Hostname unavailable; localhost suffices.
}
AddNetworkNamesAndAddresses(dnsNames, ipAddresses, hostName);
// A cloud VM's public IP lives on the provider's edge, not the NIC —
// discover it (metadata service, then an echo) so direct HTTPS to the
// public address validates. Best-effort and time-bounded, and only
// when we're actually generating a self-signed cert (never in tests
// or when TLS is off) so it makes no network calls otherwise.
if (enabled)
{
AddPublicIpAddresses(ipAddresses);
}
// A configured public URL's host (name or IP) belongs in the SANs too.
if (configuration["PUBLIC_SERVER_URL"] is { Length: > 0 } publicUrl
&& Uri.TryCreate(publicUrl, UriKind.Absolute, out var publicUri))
{
if (IPAddress.TryParse(publicUri.Host, out var publicIp))
{
if (!ipAddresses.Contains(publicIp))
{
ipAddresses.Add(publicIp);
}
}
else
{
AddDns(dnsNames, publicUri.Host);
}
}
foreach (var url in (configuration["urls"] ?? string.Empty)
.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
{
@@ -96,7 +128,7 @@ public sealed class TlsSettings
return new TlsSettings
{
Enabled = configuration["TLS_SELF_SIGNED"] != "0",
Enabled = enabled,
CertificateDirectory = certDir is { Length: > 0 } ? certDir : Path.Combine(dataDir, "tls"),
UseWindowsStore = OperatingSystem.IsWindows() && certDir is not { Length: > 0 },
DnsNames = dnsNames,
@@ -104,6 +136,160 @@ public sealed class TlsSettings
};
}
/// <summary>
/// Walks every operational network adapter: adds each adapter's DNS suffix
/// (and hostname.suffix), the global domain name, and every unicast IP.
/// </summary>
private static void AddNetworkNamesAndAddresses(
List<string> dnsNames, List<IPAddress> ipAddresses, string? hostName)
{
try
{
var domain = System.Net.NetworkInformation.IPGlobalProperties.GetIPGlobalProperties().DomainName;
if (!string.IsNullOrWhiteSpace(domain) && hostName is { Length: > 0 })
{
AddDns(dnsNames, $"{hostName}.{domain}");
}
}
catch (Exception)
{
// Global properties unavailable on this host.
}
try
{
foreach (var nic in System.Net.NetworkInformation.NetworkInterface.GetAllNetworkInterfaces())
{
if (nic.OperationalStatus != System.Net.NetworkInformation.OperationalStatus.Up)
{
continue;
}
var props = nic.GetIPProperties();
if (hostName is { Length: > 0 } && !string.IsNullOrWhiteSpace(props.DnsSuffix))
{
AddDns(dnsNames, $"{hostName}.{props.DnsSuffix}");
}
foreach (var unicast in props.UnicastAddresses)
{
var ip = unicast.Address;
// Skip link-local (fe80::) — noisy and not a stable SAN.
if (ip.IsIPv6LinkLocal || ipAddresses.Contains(ip))
{
continue;
}
ipAddresses.Add(ip);
}
}
}
catch (Exception)
{
// Adapter enumeration unavailable; the base SANs still apply.
}
}
/// <summary>
/// Best-effort public IP discovery so a cloud instance's public address is
/// in the cert. Tries the local cloud metadata services (Azure/GCP/AWS —
/// fast-fail off-cloud) then a public echo, within a small overall budget.
/// </summary>
private static void AddPublicIpAddresses(List<IPAddress> ipAddresses)
{
try
{
foreach (var raw in DiscoverPublicIpsAsync().GetAwaiter().GetResult())
{
if (IPAddress.TryParse(raw, out var ip) && !ipAddresses.Contains(ip)
&& !IsPrivateOrReserved(ip))
{
ipAddresses.Add(ip);
}
}
}
catch (Exception)
{
// Never let discovery block or fail certificate generation.
}
}
private static async Task<IEnumerable<string>> DiscoverPublicIpsAsync()
{
using var budget = new CancellationTokenSource(TimeSpan.FromSeconds(3));
var found = new List<string>();
async Task<string?> GetAsync(string url, (string, string)? header, TimeSpan timeout)
{
try
{
using var http = new HttpClient { Timeout = timeout };
using var request = new HttpRequestMessage(HttpMethod.Get, url);
if (header is { } h)
{
request.Headers.TryAddWithoutValidation(h.Item1, h.Item2);
}
using var response = await http.SendAsync(request, budget.Token);
if (!response.IsSuccessStatusCode)
{
return null;
}
return (await response.Content.ReadAsStringAsync(budget.Token)).Trim().Trim('"');
}
catch (Exception)
{
return null;
}
}
// Local metadata services fail fast when this isn't that cloud.
var azure = await GetAsync(
"http://169.254.169.254/metadata/instance/network/interface/0/ipv4/ipAddress/0/publicIpAddress?api-version=2021-02-01&format=text",
("Metadata", "true"), TimeSpan.FromMilliseconds(800));
if (!string.IsNullOrWhiteSpace(azure)) { found.Add(azure); }
var gcp = await GetAsync(
"http://metadata.google.internal/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip",
("Metadata-Flavor", "Google"), TimeSpan.FromMilliseconds(800));
if (!string.IsNullOrWhiteSpace(gcp)) { found.Add(gcp); }
var aws = await GetAsync(
"http://169.254.169.254/latest/meta-data/public-ipv4", null, TimeSpan.FromMilliseconds(800));
if (!string.IsNullOrWhiteSpace(aws)) { found.Add(aws); }
// Provider-agnostic fallback if metadata yielded nothing.
if (found.Count == 0)
{
var echo = await GetAsync("https://api.ipify.org", null, TimeSpan.FromSeconds(1.5));
if (!string.IsNullOrWhiteSpace(echo)) { found.Add(echo); }
}
return found;
}
/// <summary>True for loopback, link-local, and RFC1918/CGNAT/ULA ranges.</summary>
private static bool IsPrivateOrReserved(IPAddress ip)
{
if (IPAddress.IsLoopback(ip) || ip.IsIPv6LinkLocal || ip.IsIPv6SiteLocal || ip.IsIPv6UniqueLocal)
{
return true;
}
if (ip.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork)
{
var b = ip.GetAddressBytes();
return b[0] == 10
|| (b[0] == 172 && b[1] >= 16 && b[1] <= 31)
|| (b[0] == 192 && b[1] == 168)
|| (b[0] == 169 && b[1] == 254) // link-local / APIPA
|| (b[0] == 100 && b[1] >= 64 && b[1] <= 127); // CGNAT
}
return false;
}
private static void AddDns(List<string> names, string candidate)
{
if (!string.IsNullOrWhiteSpace(candidate)
+54
View File
@@ -125,6 +125,22 @@
Impersonate="no"
Return="ignore" />
<!-- Clean uninstall: PURGEDATA=1 (Remove page checkbox, or property on
a silent uninstall) forgets the self-signed chain and deletes the
generated data/logs/secrets/appsettings. Runs while the binary
still exists (before RemoveFiles). -->
<Property Id="PURGEDATA" Secure="yes" />
<SetProperty Id="PurgeServerData"
Value="&quot;[INSTALLFOLDER]ExecuteR-Server.exe&quot; purge --yes"
Sequence="execute"
Before="PurgeServerData" />
<CustomAction Id="PurgeServerData"
BinaryRef="Wix4UtilCA_X64"
DllEntry="WixQuietExec64"
Execute="deferred"
Impersonate="no"
Return="ignore" />
<!--
Interactive UI: Welcome → Administrator account → Verify → Progress.
The account page edits the same ADMINUSERNAME / ADMINPASSWORD public
@@ -218,15 +234,50 @@
</Control>
</Dialog>
<!-- Uninstall: offer a clean removal (data, keys, self-signed certs). -->
<Dialog Id="PurgeDlg" Width="370" Height="270" Title="ExecuteR Server Setup">
<Control Id="BannerBitmap" Type="Bitmap" X="0" Y="0" Width="370" Height="44"
TabSkip="no" Text="!(loc.InstallDirDlgBannerBitmap)" />
<Control Id="Title" Type="Text" X="15" Y="6" Width="330" Height="15"
Transparent="yes" NoPrefix="yes"
Text="{\WixUI_Font_Title}Remove ExecuteR Server" />
<Control Id="Description" Type="Text" X="25" Y="23" Width="330" Height="15"
Transparent="yes" NoPrefix="yes"
Text="Choose whether to leave data behind or remove everything." />
<Control Id="BannerLine" Type="Line" X="0" Y="44" Width="370" Height="0" />
<Control Id="PurgeCheck" Type="CheckBox" X="20" Y="70" Width="330" Height="14"
Property="PURGEDATA" CheckBoxValue="1"
Text="Also remove all data, keys and self-signed certificates" />
<Control Id="PurgeNote" Type="Text" X="32" Y="88" Width="318" Height="60" NoPrefix="yes"
Text="Leave unchecked to keep the database, sign-in and generated certificates for a reinstall.&#13;&#10;&#13;&#10;Checked deletes appsettings.json, data, logs and secrets, and removes the managed self-signed chain from the Windows certificate stores. This cannot be undone." />
<Control Id="BottomLine" Type="Line" X="0" Y="234" Width="370" Height="0" />
<Control Id="Back" Type="PushButton" X="180" Y="243" Width="56" Height="17"
Text="!(loc.WixUIBack)" />
<Control Id="Next" Type="PushButton" X="236" Y="243" Width="56" Height="17"
Default="yes" Text="!(loc.WixUINext)" />
<Control Id="Cancel" Type="PushButton" X="304" Y="243" Width="56" Height="17"
Cancel="yes" Text="!(loc.WixUICancel)">
<Publish Event="SpawnDialog" Value="CancelDlg" />
</Control>
</Dialog>
<!-- Splice the pages in: overrides outrank the stock set's publishes. -->
<Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="ServerConfigDlg"
Order="99" Condition="NOT Installed" />
<Publish Dialog="MaintenanceTypeDlg" Control="RemoveButton" Event="NewDialog" Value="PurgeDlg"
Order="99" Condition="1" />
<Publish Dialog="PurgeDlg" Control="Back" Event="NewDialog" Value="MaintenanceTypeDlg" />
<Publish Dialog="PurgeDlg" Control="Next" Event="NewDialog" Value="VerifyReadyDlg" />
<Publish Dialog="ServerConfigDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg" />
<Publish Dialog="ServerConfigDlg" Control="Next" Event="NewDialog" Value="ServerNetworkDlg" />
<Publish Dialog="ServerNetworkDlg" Control="Back" Event="NewDialog" Value="ServerConfigDlg" />
<Publish Dialog="ServerNetworkDlg" Control="Next" Event="NewDialog" Value="VerifyReadyDlg" />
<Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="ServerNetworkDlg"
Order="99" Condition="NOT Installed" />
<Publish Dialog="VerifyReadyDlg" Control="Back" Event="NewDialog" Value="PurgeDlg"
Order="98" Condition="Installed AND REMOVE=&quot;ALL&quot;" />
<!-- Open the UI on Finish: wildcard binds resolve to localhost and the
scheme follows the Self-Signed TLS checkbox. With TLS on, the
@@ -258,6 +309,9 @@
<Custom Action="UninstallServerService"
After="InstallInitialize"
Condition="REMOVE=&quot;ALL&quot; AND NOT UPGRADINGPRODUCTCODE" />
<Custom Action="PurgeServerData"
Before="RemoveFiles"
Condition="REMOVE=&quot;ALL&quot; AND NOT UPGRADINGPRODUCTCODE AND PURGEDATA=&quot;1&quot;" />
</InstallExecuteSequence>
</Package>
+11
View File
@@ -142,5 +142,16 @@
<text id="ProxyUrl_Text" valueName="ProxyUrl" required="true" maxLength="2048" />
</elements>
</policy>
<!-- ServerCaAutoInstall (REG_DWORD) -->
<policy name="ServerCaAutoInstall" class="Machine" displayName="$(string.ServerCaAutoInstall)"
explainText="$(string.ServerCaAutoInstall_Help)"
key="SOFTWARE\Policies\ExecuteR"
valueName="ServerCaAutoInstall">
<parentCategory ref="ExecuteR" />
<supportedOn ref="SUPPORTED_ExecuteR_1_0" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
</policies>
</policyDefinitions>
@@ -111,6 +111,17 @@ If you disable or do not configure this policy, the agent uses the locally confi
Do not enable this for servers reached through a proxy with a publicly trusted certificate — leave validation on there. Always follow your organization's security standards.
The agent reads configuration at service start; restart the "ExecuteR Agent" service (ExecuteRAgent) to apply a change immediately.</string>
<string id="ServerCaAutoInstall">Install the server's self-signed CA</string>
<string id="ServerCaAutoInstall_Help">Installs the ExecuteR server's managed self-signed CA (root + intermediate) into the machine trust store, and keeps it current when the server rotates its chain.
If you enable this policy, ordinary system certificate validation trusts a direct or local connection to a self-signed server. It is not certificate pinning and it is not forced: if the server is later reached through a reverse proxy presenting a publicly trusted certificate, that certificate validates normally and the installed self-signed CA simply goes unused.
If you disable or do not configure this policy, the agent does not install the CA. Use this for a self-signed server without a proxy; leave it off when a real edge certificate is in front.
For an accept-any escape hatch (no validation at all), see "Skip TLS certificate verification" instead.
The agent reads configuration at service start; restart the "ExecuteR Agent" service (ExecuteRAgent) to apply a change immediately.</string>
<string id="ProxyUrl">Outbound proxy URL</string>
+16 -4
View File
@@ -5,7 +5,7 @@
<!--
ExecuteR Agent MSI.
Public properties (uppercase): SERVERURL BOOTSTRAPTOKEN LOGLEVEL
ALLOWREMOTESHELL ALLOWSCRIPTEXECUTION SKIPTLSVERIFY PROXYURL.
ALLOWREMOTESHELL ALLOWSCRIPTEXECUTION SKIPTLSVERIFY PROXYURL CAINSTALL.
Remember-property pattern: existing registry values are read back into
the properties at install start, so blank properties never overwrite
configured values and upgrades preserve configuration.
@@ -76,6 +76,14 @@
<RegistrySearch Id="ExistingProxyUrl" Root="HKLM"
Key="$(var.AgentRegKey)" Name="ProxyUrl" Type="raw" />
</Property>
<!-- CAINSTALL=1: install the server's managed self-signed CA into the OS
trust store (kept current) so system validation trusts a direct
self-signed server. Not pinning; a real cert behind a proxy still
validates normally. -->
<Property Id="CAINSTALL">
<RegistrySearch Id="ExistingServerCaAutoInstall" Root="HKLM"
Key="$(var.AgentRegKey)" Name="ServerCaAutoInstall" Type="raw" />
</Property>
<StandardDirectory Id="ProgramFiles64Folder">
<Directory Id="ExecuteRFolder" Name="ExecuteR">
@@ -149,6 +157,10 @@
<RegistryValue Root="HKLM" Key="$(var.AgentRegKey)"
Name="ProxyUrl" Type="string" Value="[PROXYURL]" KeyPath="yes" />
</Component>
<Component Id="RegServerCaAutoInstall" Guid="a1f5c2e7-8d43-4b9a-bc16-7e0d9f42a3b8" Condition="CAINSTALL">
<RegistryValue Root="HKLM" Key="$(var.AgentRegKey)"
Name="ServerCaAutoInstall" Type="integer" Value="[CAINSTALL]" KeyPath="yes" />
</Component>
</ComponentGroup>
@@ -222,9 +234,9 @@
Text="Blank keeps values already configured (upgrades), or set later via registry / Group Policy. The service enrolls once both values are present.&#13;&#10;&#13;&#10;Silent: SERVERURL=... BOOTSTRAPTOKEN=..." />
<!-- Unchecked by default; prefilled from the registry on upgrades. -->
<Control Id="SkipTlsCheck" Type="CheckBox" X="20" Y="192" Width="330" Height="14"
Property="SKIPTLSVERIFY" CheckBoxValue="1"
Text="Skip TLS verification (self-signed server; traffic stays encrypted)" />
<Control Id="CaInstallCheck" Type="CheckBox" X="20" Y="192" Width="330" Height="14"
Property="CAINSTALL" CheckBoxValue="1"
Text="Trust self-signed server (install its CA into the trust store)" />
<Control Id="BottomLine" Type="Line" X="0" Y="234" Width="370" Height="0" />
<Control Id="Back" Type="PushButton" X="180" Y="243" Width="56" Height="17"
+3
View File
@@ -65,6 +65,9 @@ public static class ApiRoutes
public const string Dashboard = "/api/dashboard";
/// <summary>Public self-signed CA chain (root + intermediate) for agent trust.</summary>
public const string EnrollmentCaChain = "/api/enrollment/ca";
public const string Schedules = "/api/schedules";
public const string Schedule = "/api/schedules/{id}";
public const string SchedulePreview = "/api/schedules/preview";
@@ -194,8 +194,8 @@
{/if}
<label class="radio">
<input type="checkbox" bind:checked={skipTlsVerify} />
Skip TLS verification
<span class="faint">(self-signed server without a proxy — traffic stays encrypted)</span>
Trust self-signed certificate
<span class="faint">(self-signed server without a proxy — installs its CA so system trust works)</span>
</label>
</div>
+1 -1
View File
@@ -136,7 +136,7 @@
<div class="install-cmd mono">{installCommand}</div>
<label class="faint small">
<input type="checkbox" bind:checked={skipTlsVerify} />
Skip TLS verification (self-signed server without a proxy — traffic stays encrypted)
Trust self-signed certificate (self-signed server without a proxy — installs its CA so system trust works)
</label>
<button class="btn" onclick={copyCommand}>{copiedCmd ? '✔ Copied' : 'Copy command'}</button>
<div class="faint small">
+1 -1
View File
@@ -22,7 +22,7 @@ export default defineConfig({
})
],
server: {
// Local development against `docker compose -f docker-compose.yml -f docker-compose.dev.yml up`
// Local development against `docker compose -f IaC/compose/docker-compose.yml -f IaC/compose/docker-compose.dev.yml up`
// (or a locally running backend + NATS). Production is same-origin via the reverse proxy.
proxy: {
'/api': {
+17 -6
View File
@@ -161,20 +161,31 @@ public class InstallScriptTests(BackendTestFixture fixture) : IClassFixture<Back
using var client = fixture.CreateClient();
var msi = await (await client.GetAsync("/api/enrollment/install?token=t&skipVerify=1")).Content.ReadAsStringAsync();
Assert.Contains("ServerCertificateValidationCallback", msi); // PS 5.1 path
Assert.Contains("SkipCertificateCheck", msi); // PS 7 path
Assert.Contains("SKIPTLSVERIFY=1", msi);
Assert.Contains("ServerCertificateValidationCallback", msi); // PS 5.1 download path
Assert.Contains("SkipCertificateCheck", msi); // PS 7 download path
Assert.Contains("CAINSTALL=1", msi);
var zip = await (await client.GetAsync("/api/enrollment/install?token=t&type=zip&skipVerify=1")).Content.ReadAsStringAsync();
Assert.Contains("ServerCertificateValidationCallback", zip);
Assert.Contains("TlsSkipVerify", zip);
Assert.Contains("ServerCaAutoInstall", zip);
var bash = await (await client.GetAsync("/api/enrollment/install?token=t&type=linux&skipVerify=1")).Content.ReadAsStringAsync();
Assert.Contains("curl -fsSLk", bash);
Assert.Contains("--skip-tls-verify", bash);
Assert.Contains("--install-server-ca", bash);
var plain = await (await client.GetAsync("/api/enrollment/install?token=t")).Content.ReadAsStringAsync();
Assert.DoesNotContain("ServerCertificateValidationCallback", plain);
Assert.DoesNotContain("SKIPTLSVERIFY", plain);
Assert.DoesNotContain("CAINSTALL", plain);
Assert.DoesNotContain("--install-server-ca", plain);
}
[Fact]
public async Task CaChainIs404WhenNotSelfSigned()
{
// The test fixture runs plain HTTP (TLS_SELF_SIGNED off), so there is
// no managed chain to distribute.
using var client = fixture.CreateClient();
var response = await client.GetAsync("/api/enrollment/ca");
Assert.Equal(System.Net.HttpStatusCode.NotFound, response.StatusCode);
}
}