Files
Alphaeus Mote 890bab034b
CI / build-test (push) Successful in 38m1s
CI / images (push) Has been skipped
Release / release (push) Successful in 19m58s
Release / images (push) Successful in 12m49s
fix: devices follow the real server address; static screen host
- PUBLIC_SERVER_URL and TRUSTED_HOSTS left at .env.example's sample
  (control.example.com, any RFC 2606 name) are ignored with a startup
  warning: links follow the forwarded headers and devices download from
  the server URL they already use. .env.example ships them empty and
  deploy.sh clears sample values from an existing .env.
- The screen host is built from its own folder so .cargo/config.toml's
  +crt-static applies; the shipped exe imported VCRUNTIME140.dll and died
  without output on devices without the Visual C++ runtime ("the screen
  host gave no answer"). The build now refuses an exe with CRT imports.
- A failed screen host probe is retried with backoff (30 s up to 10 min)
  and the inventory is republished once it answers; the warning and the
  reason carry the exit code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 20:02:03 -05:00

267 lines
15 KiB
Bash
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#=============================================================================
# ExecuteR - Windows endpoint management control plane
#=============================================================================
#
# CREDENTIALS:
# Initial admin: generated at first start into /data/initial-admin-password.txt
# (INITIAL_ADMIN_PASSWORD below sets one instead)
# NATS seeds: generated into secrets/nats by scripts/New-LocalSecrets.ps1
# Database: DATABASE_PASSWORD generated by deploy.sh / New-LocalSecrets.ps1
#
# ACCESS URL: nothing to set — the server takes its address from the proxy's
# forwarded headers. PUBLIC_SERVER_URL pins one (optional).
#
# PRODUCTION SETUP:
# 1. cp .env.example .env (or run scripts/New-LocalSecrets.ps1)
# 2. Fill NATS_ACCOUNT_SIGNING_SEED and DATABASE_PASSWORD (and INITIAL_ADMIN_PASSWORD only to choose it)
# 3. docker compose -f IaC/compose/docker-compose.yml up -d --build (or ./scripts/deploy.sh)
#
#=============================================================================
# ── Stack identity ─────────────────────────────────────────────────────────
# Compose project name and bind-mount root. Container and network names are
# static (EXECUTER-API-00001, EXECUTER-EXTERNAL, ...) and not derived from these.
STACK_NAME=stk-executer-00001
STACK_BINDMOUNTROOT=/mnt/data/docker/stacks
# ── Images ─────────────────────────────────────────────────────────────────
# Published by CI to Gitea's OWN container registry, which lives on the Gitea
# host itself. REGISTRY is "<gitea-host>/<owner>", all lowercase — e.g.
# git.example.com/platform
# deploy.sh pulls these and builds from source only if the pull fails.
REGISTRY=prod.git.gracesolution.info/gsadmin
BACKEND_IMAGE=executer-backend
WEBUI_IMAGE=executer-webui
BACKEND_VERSION=latest
WEBUI_VERSION=latest
# missing = use local/pull once; always = re-pull every deploy; never = local only
IMAGE_PULL_POLICY=missing
# Needed only to PULL from a private repo's packages. Any Gitea account token
# works as the password. CI does not need these — Actions injects its own.
REGISTRY_USERNAME=
REGISTRY_TOKEN=
# Infrastructure images are pinned by digest.
NATS_IMAGE=nats
NATS_VERSION=2.12-alpine@sha256:7cef1bd3fed6034e95cf6e6bc9c28c5afa6dc58e9fb778dd7924a1ac62569f2d
# The bundled database; a new major needs a dump and restore (README, Database providers).
POSTGRES_IMAGE=postgres
POSTGRES_VERSION=18-trixie@sha256:e3d24f6906d0760bf4da0dae872415391ededefad23fd471c47dc53b0ddf3c42
# Optional in-stack reverse proxy (IaC/compose/docker-compose.proxy.yml, opt-in)
NGINX_IMAGE=nginx
NGINX_VERSION=1.29-alpine
# The bundled proxy is the edge: it takes the standard 80/443 on the host (a VPS
# running only ExecuteR), while the app services stay on their own upstream
# ports below, on loopback. Pick other ports only when something else owns
# 80/443 (HTTP then only redirects to the HTTPS port given here).
PROXY_HTTP_PORT=80
PROXY_HTTPS_PORT=443
# The bundled proxy's hostname (deploy.sh --host sets it), e.g. control.example.com.
PROXY_PUBLIC_HOSTNAME=
# ── Host-published ports (uncommon range; front with the edge proxy) ───────
# Which host address the app services (backend, webui, NATS WebSocket)
# publish on. Empty (the default) means 0.0.0.0 — all interfaces — so an
# edge proxy on ANOTHER host can reach them directly. The bundled proxy
# (deploy.sh --with-proxy) flips the default to 127.0.0.1 instead, since it
# reaches the services over the compose network and the ports need not be
# public. Set an explicit value here to pin either case (it always wins);
# use a specific host IP to publish on just one interface. The bundled proxy
# binds publicly via PROXY_BIND_ADDRESS.
BIND_EXTERNAL_ADDRESS=
PROXY_BIND_ADDRESS=0.0.0.0
WEBUI_PORT=13080
BACKEND_PORT=19080
NATS_WS_PORT=19222
# ── Container user ─────────────────────────────────────────────────────────
# The backend/webui containers run as this user; remap when bind-mount
# ownership needs it.
PUID=1000
PGID=1000
# ── Public edge ────────────────────────────────────────────────────────────
# Empty (the default): links shown in the console follow the address the proxy
# forwards (X-Forwarded-Host/Proto/Port), and devices download from the server
# URL they already reach. Set it only to pin one address for everything,
# e.g. https://control.example.com (sample names like that one are ignored).
PUBLIC_SERVER_URL=
# ── Reverse proxy trust ────────────────────────────────────────────────────
# Forwarded headers are trusted BY DEFAULT from private address space
# (loopback, RFC1918, CGNAT), so no configuration is needed behind a typical
# cloud or LAN reverse proxy. Setting TRUSTED_PROXIES / TRUSTED_NETWORKS
# replaces those defaults with an explicit allow-list — narrow this when
# untrusted peers share your private network. TRUST_PROXY=0 disables
# forwarded-header processing entirely.
TRUST_PROXY=1
TRUSTED_PROXIES=
TRUSTED_NETWORKS=
# Empty accepts any forwarded host; a list (e.g. control.example.com) accepts only those.
TRUSTED_HOSTS=
FORWARD_LIMIT=1
# ── Built-in encryption (self-signed) ──────────────────────────────────────
# TLS_SELF_SIGNED=1 makes the backend serve HTTPS with a chain it manages
# itself (root > intermediate > leaf, auto-renewed). Reverse proxies then
# either SKIP verification — not insecure: the hop is still encrypted, the
# roots simply are not distributed — or import root.crt + intermediate.crt
# to establish trust (re-import when they rotate at expiry). Always follow
# your organization's security standards. The chain is PEM files under
# <data>/tls (TLS_CERT_DIR overrides; keep it on a persisted volume, and
# switch the proxy upstream + health checks to https accordingly).
# The root and intermediate alone (no keys) are also written to
# <data>/ca-certificates as .cer and .pem, for Group Policy or a proxy.
TLS_SELF_SIGNED=0
TLS_CERT_DIR=
# Your own certificate instead (turns HTTPS on by itself; hot-reloaded within
# a minute when the file is replaced): TLS_CERT_SOURCE=file with
# TLS_CERT_FILE a PFX/P12 (TLS_CERT_PASSWORD) or a PEM (a fullchain PEM
# brings its intermediates) with TLS_CERT_KEY_FILE, mounted read-only into the
# container. On Windows, TLS_CERT_SOURCE=store + TLS_CERT_THUMBPRINT serves a
# LocalMachine\My certificate. When its chain is not publicly trusted (an
# enterprise CA) agents are handed that chain, pinned to the token, as with the
# self-signed one; TLS_DISTRIBUTE_CA=1/0 overrides that decision.
TLS_CERT_SOURCE=
TLS_CERT_FILE=
TLS_CERT_KEY_FILE=
TLS_CERT_PASSWORD=
TLS_DISTRIBUTE_CA=
# ── Execution history ──────────────────────────────────────────────────────
# Newest jobs kept per device (older jobs and their stored output are
# pruned). 0 disables pruning.
JOB_HISTORY_LIMIT=200
# ── Job dispatch ───────────────────────────────────────────────────────────
# Commands sealed and published at once when a run starts on many devices,
# and within each paced batch of agent upgrades (1 to 128; 1 sends one at a
# time). Rows are written 500 per transaction whatever this is; a stagger's
# slots and the upgrades' StartWithinMinutes pacing are kept either way.
JOB_DISPATCH_PARALLELISM=16
# ── Break-glass account (first startup only) ───────────────────────────────
# The one recovery built-in account. Left empty (the default), a one-time
# password is generated at the first start and written to
# /data/initial-admin-password.txt (mode 600, never the log); it must be
# changed at the first sign-in, and the file goes once it is. Read it with
# docker exec EXECUTER-API-00001 cat /data/initial-admin-password.txt
# Locked out or lost: docker exec EXECUTER-API-00001 dotnet Backend.dll reset-admin
# Set a password here only to choose it yourself (existing deployments keep theirs).
INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_PASSWORD=
# ── Sign-in ────────────────────────────────────────────────────────────────
# Sign-in methods (Built-In, Local Windows Accounts, LDAP, OIDC) are set in
# Settings › Authentication. The OIDC_* and AUTH_LOGIN_MODE values below are
# read once, to carry an older install's settings over when no sign-in
# settings exist yet; after that the console is the only place to change them.
# The OIDC callback to register is <public-url>/api/auth/oidc/callback.
OIDC_ENABLED=0
OIDC_AUTHORITY=
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
# Friendly name shown on the sign-in button (Authentik, Entra ID, Keycloak…)
OIDC_PROVIDER_NAME=
OIDC_SCOPES="openid profile email"
OIDC_NAME_CLAIM=
OIDC_ROLE_CLAIM=
OIDC_ADMIN_ROLE=
OIDC_OPERATOR_ROLE=
OIDC_VIEWER_ROLE=
OIDC_DEFAULT_ROLE=Operator
OIDC_REQUIRE_MAPPED_ROLE=0
# LocalOnly | Both | OidcOnly | OidcAutoRedirect
AUTH_LOGIN_MODE=Both
# Always offer the built-in form, whatever the saved settings say (a way back in).
AUTH_FORCE_LOCAL=0
# ── NATS decentralized auth (generated — do NOT hand-edit) ─────────────────
# These MUST be real Ed25519 NKeys from scripts/New-LocalSecrets.ps1
# (or `dotnet run --project src/Backend -- nats-auth init`). A random string
# here will not work — the signing seed must match the resolver's account.
NATS_ACCOUNT_SIGNING_SEED=
NATS_ACCOUNT_PUBLIC_KEY=
NATS_OPERATOR_PUBLIC_KEY=
# ── S3 file delivery (optional) ────────────────────────────────────────────
# Enables presigned-URL file downloads to devices. Any S3-compatible store
# (AWS S3, MinIO, Backblaze B2, etc.).
# S3 works without any of this: the server runs a built-in store (files under
# /data/object-store) and devices download through the server's own address.
# S3_ENABLED=1 below uses an external store instead. S3_EMBEDDED=0 removes the
# built-in one altogether.
S3_EMBEDDED=1
S3_ENABLED=0
S3_ENDPOINT=
S3_REGION=us-east-1
S3_BUCKET=
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_FORCE_PATH_STYLE=1
S3_PRESIGN_EXPIRY_SECONDS=900
# ── Database ───────────────────────────────────────────────────────────────
# postgres (default: the bundled container EXECUTER-DB-00001) | sqlite (/data/app.db) | sqlserver.
# deploy.sh keeps an existing install on SQLite: no provider set and an app.db in API/Data → sqlite.
DATABASE_PROVIDER=postgres
# The bundled Postgres as is; your own: Host=db.example.com;Port=5432;Database=executer;Username=executer
# sqlserver: Server=db;Database=executer;User Id=sa;TrustServerCertificate=True — empty for sqlite. Keep the quotes.
DATABASE_CONNECTION_STRING="Host=postgres;Port=5432;Database=executer;Username=executer"
# Generated by deploy.sh / New-LocalSecrets.ps1 for a new .env (also the bundled server's own); never commit it.
DATABASE_PASSWORD=
# "postgres" starts the bundled server; deploy.sh sets it from the provider (empty for sqlite or your own server).
COMPOSE_PROFILES=postgres
# Opt-in host port for the bundled Postgres (e.g. POSTGRES_BIND=127.0.0.1); empty publishes nothing.
POSTGRES_BIND=
POSTGRES_PORT=15432
# Backups (Settings › Database, SQLite and Postgres) land here inside the container; /data is the backend's data bind mount.
DATABASE_BACKUP_PATH=/data/backups
# ── Logging (Serilog: console + rolling file) ──────────────────────────────
# Server defaults: roll at 10 MB, keep the last 7 files (~70 MB ceiling).
# The agent defaults to 5 MB / 3 files and is configured via GPO or registry.
LOG_LEVEL=Information
LOG_JSON=0
LOG_DIRECTORY=/data/logs
LOG_RETAIN_FILES=7
LOG_MAX_BYTES=10485760
# ── Agent package for URL install (irm | iex) ──────────────────────────────
# Directory (inside the backend container) holding Agent.msi / Agent.zip that
# the URL install command downloads. Defaults to /data/agent (under API data).
AGENT_PACKAGE_PATH=/data/agent
# ── Build / version ────────────────────────────────────────────────────────
# X.Y.Z (a release) or X.Y.Z.N (N commits after it), never yyyy.MM.dd.HHmm.
# Picks the image tag to pull (empty = latest) and stamps a local build;
# CI sets it, scripts/Get-Version.ps1 and deploy.sh derive it from git.
UNIFIED_VERSION=
# ── Device lifecycle ───────────────────────────────────────────────────────
# A device silent for this many days is orphaned: refused credential refresh
# and job dispatch until it re-enrolls with a fresh bootstrap token.
# Set to 0 to disable orphaning, so silent devices simply go Stale then
# Offline and reconnect on their own. Default (unset) is 30.
DEVICE_ORPHAN_AFTER_DAYS=30
# ── Automatic image updates (off by default) ───────────────────────────────
# Every service ships opt-out labels for the common updaters — Watchtower
# (com.centurylinklabs.watchtower.enable), Diun (diun.enable), What's Up
# Docker (wud.watch) and Dockhand (dockhand.update) — all driven by the
# per-service toggles below, which default to false, so nothing updates the
# stack until you opt in. (Dockhand auto-updates by default and its label
# overrides the UI/environment, so the false label is what keeps it off here.)
# When you do enable one, pin a minor tag (e.g. BACKEND_VERSION=1.3 /
# WEBUI_VERSION=1.3) and turn backend and webui on together, so a mid-stream
# pull can never leave the API and console on mismatched versions.
NATS_ENABLEAUTOMATICUPDATES=false
# Leave off: the tag is pinned by digest and a new Postgres major needs a dump and restore.
POSTGRES_ENABLEAUTOMATICUPDATES=false
BACKEND_ENABLEAUTOMATICUPDATES=false
WEBUI_ENABLEAUTOMATICUPDATES=false
PROXY_ENABLEAUTOMATICUPDATES=false