Running Entrosity Vertex

Entrosity Vertex (entrosity-vertex.backend, binary vertex-server) is an API server with its own PostgreSQL database. It runs next to Entrosity Hub and Axis and needs both: users sign in on the Hub, and every directory request runs as a job on an Axis connector, which Vertex reaches through Axis's internal API. Vertex has no connector, no connector releases and no public port besides the API behind the proxy.

Not deployed yet

The backend and its API are ready; the web interface is in development, and Vertex is not part of the entrosity-infra compose stack yet (no compose service, no Caddy route for /vertex). The Hub registers the product disabled, so nothing links to it until it is deployed and enabled (Enabling Vertex later).

Part	Where
API	https://hub.entrosity.com/vertex/api/v1 once deployed; the proxy strips /vertex, so the backend serves /api/v1
Internal API for Axis	VERTEX_INTERNAL_ADDR (:8088), container network only
Metrics	VERTEX_METRICS_ADDR (:9096), container network only
Database	Its own PostgreSQL database, migrated by vertex-server migrate up; the server connects as vertex_app (row-level security)
Sign-in	Entrosity Hub, product vertex

Listeners and ports

Listener	Default	Purpose
VERTEX_HTTP_ADDR	:8087	The API (/api/v1, /healthz, /readyz). The production container sets :8080, behind the proxy.
VERTEX_INTERNAL_ADDR	:8088	Internal API for Axis: the connectors' secrets requests, result chunks and finished-job hints (Vertex protocol). Bearer VERTEX_AXIS_TOKEN. Never expose it publicly. Must differ from the other two.
VERTEX_METRICS_ADDR	:9096	Prometheus /metrics. Never expose it publicly; empty disables it.

Vertex in turn calls Axis's internal listener (RMM_INTERNAL_ADDR, :8089) and the Hub's internal API. None of these needs a firewall opening to the Internet.

vertex-server serve        run the HTTP API and the background work (default)
vertex-server migrate [cmd] database migrations: up | down [N] | version | force N
                           (up also sets the vertex_app login password when
                           VERTEX_APP_DATABASE_PASSWORD is set)
vertex-server healthcheck  exit 0 when this server is ready (/readyz)
vertex-server version      print the version

Configuration reference

The server is configured only through VERTEX_* environment variables (entrosity-vertex.backend/internal/config). Invalid values stop it at start with a list of every problem. The RETENTION section accepts one or two underscores: VERTEX_RETENTION_JOB_DAYS = VERTEX_RETENTION__JOB_DAYS.

Server

Variable	Default	Meaning
VERTEX_ENV	dev	dev, test or prod. prod refuses the development example secrets (values containing dev-only).
VERTEX_PUBLIC_URL	http://localhost:8087	Vertex's public address including the /vertex prefix the proxy strips (https://hub.entrosity.com/vertex).
VERTEX_HTTP_ADDR	:8087	API listener.
VERTEX_INTERNAL_ADDR	:8088	Internal API for Axis. Required.
VERTEX_METRICS_ADDR	:9096	Metrics listener; empty disables it.
VERTEX_LOG_LEVEL	info	debug, info, warn or error.
VERTEX_CORS_ORIGINS	http://localhost:5179	Allowed browser origins, comma separated, no wildcards or paths (production: https://hub.entrosity.com).
VERTEX_TRUSTED_PROXIES	none	CIDRs or IPs allowed to set X-Forwarded-For; the client IP in the audit log comes from it.
VERTEX_API_RATE_PER_SECOND, VERTEX_API_RATE_BURST	20, 60	API rate limit per client IP.

Database

Variable	Default	Meaning
VERTEX_DATABASE_URL	none (required)	Connection URL.
VERTEX_DATABASE_ROLE	vertex_app	Role the pool switches to after connecting (SET ROLE), so row-level security applies; empty when the login already is the application role.
VERTEX_DATABASE_MAX_CONNS	20	Pool size.
VERTEX_DATABASE_STATEMENT_TIMEOUT	30s	Upper bound for any statement.
VERTEX_APP_DATABASE_PASSWORD	none	Read by migrate up: enables the vertex_app login with this password.

Secrets

Variable	Meaning
VERTEX_JWT_SECRET	Required. At least 32 bytes, raw or base64. Signs the one-minute live-stream tokens. Users' access tokens come from the Hub.
VERTEX_JWT_SECRET_OLD	The previous secret during a rotation.
VERTEX_CREDENTIALS_KEY	Required. Exactly 32 bytes, base64. Encrypts (AES-256-GCM) each tenant's AD account password and the passwords of pending operations and imports.
VERTEX_CREDENTIALS_KEY_OLD	The previous key during a rotation: it still decrypts.

Keep the credentials key

Without VERTEX_CREDENTIALS_KEY (or with another one) no stored AD password can be decrypted: every operation fails until each tenant's AD password has been entered again in the directory settings. Pending operations and imports with passwords cannot run. Keep a copy of the key with the deployment's secrets, apart from the database backups.

Sign-in on Entrosity Hub

Variable	Default	Meaning
VERTEX_PLATFORM_URL	none (required)	The Hub's public origin (https://hub.entrosity.com): the issuer of product tokens.
VERTEX_PLATFORM_INTERNAL_URL	none (required)	The Hub's internal API, reached directly (compose: http://platform:8081): signing keys and the access snapshot.
VERTEX_PLATFORM_TOKEN	none (required)	Vertex's bearer token on the Hub's internal API, at least 32 characters; vertex:<token> in the Hub's PLATFORM_PRODUCT_TOKENS.
VERTEX_PLATFORM_SYNC_INTERVAL	30s	How often Vertex pulls users, organizations and roles from the Hub (at least 1s).

Entrosity Axis

Variable	Default	Meaning
VERTEX_AXIS_INTERNAL_URL	none (required)	Axis's internal API (RMM_INTERNAL_ADDR), for example http://rmm:8089.
VERTEX_AXIS_TOKEN	none (required)	The bearer token of both directions between Vertex and Axis, at least 32 characters; the same value as Axis's RMM_VERTEX_AXIS_TOKEN.

Directory changes

Variable	Default	Meaning
VERTEX_CHANGE_LIMIT_USER	600	Changes per user per minute (each member and registry value counts; committed imports do not). Beyond: 429 rate_limited.
VERTEX_CHANGE_LIMIT_TENANT	2000	Changes per tenant per minute.

Retention windows

Variable	Default	Meaning
VERTEX_RETENTION_JOB_DAYS	90	Finished operations. Tenants may override it (7–730).
VERTEX_RETENTION_AUDIT_DAYS	365	Audit log. Tenants may override it (30–3650).

0 or unset keeps the default.

Generating the secrets

openssl rand -base64 32   # VERTEX_JWT_SECRET, VERTEX_CREDENTIALS_KEY (exactly 32 bytes)
openssl rand -hex 32      # VERTEX_APP_DATABASE_PASSWORD, VERTEX_PLATFORM_TOKEN, VERTEX_AXIS_TOKEN

Axis settings

Axis talks to Vertex only when these are set (Configuration):

Variable	Default	Meaning
RMM_VERTEX_INTERNAL_URL	empty (no Vertex)	Vertex's internal API, for example http://vertex:8088.
RMM_VERTEX_AXIS_TOKEN	empty	The shared bearer token: the same value as VERTEX_AXIS_TOKEN, at least 32 characters.
RMM_INTERNAL_ADDR	:8089	Axis's internal listener for Vertex (connectors, jobs). It runs only while Vertex is configured. Never expose it publicly.

With both RMM_VERTEX_* set, Axis starts the internal listener, adds the connector endpoints POST /api/connector/v1/vertex/jobs/{jobID}/secrets and …/chunks, and tells Vertex when a Vertex job finishes. Setting only one of them stops Axis at start.

On Entrosity Hub

The Hub's migration 0013 registers the product vertex (name Entrosity Vertex, base path /vertex, roles tenant_admin and helpdesk) disabled and in beta: it is hidden from the launcher and cannot be given to organizations or users. The Hub must know Vertex's token: PLATFORM_PRODUCT_TOKENS includes vertex:<token>, the same value as VERTEX_PLATFORM_TOKEN.

Enabling Vertex later

Vertex reaches users in this order; each step needs the previous one:

1. Shared protocol tagged. proto/vertex lives in entrosity-shared-go: tag a release containing it and bump entrosity-vertex.backend, entrosity-axis.backend and entrosity-axis-connector to that tag (until then they build only with a local go.work).
2. Axis and connector released. Deploy the Axis release with the internal API and the relay, and roll out the connector version with the vertex capability to the domain controllers that will run Vertex.
3. Infrastructure. Add Vertex to entrosity-infra: the database and its migration, the vertex service with the settings above, the Caddy route /vertex/api/* (stripping /vertex, unbuffered for the event stream), the internal network path between Axis and Vertex, and the shared tokens (VERTEX_AXIS_TOKEN = RMM_VERTEX_AXIS_TOKEN, vertex:<token> in the Hub's product tokens). The web interface is added at /vertex/ when it exists.
4. Enabled, in beta. A later Hub migration enables the product, as 0009 did for Matrix. It stays in beta: only platform admins see and open it.
5. Released. A platform admin chooses Release to organizations (Products in beta).

Enable it only once it answers

Enabling the product before Vertex is deployed at /vertex makes the Hub's launcher link to a product that does not answer.

Background work

vertex-server serve also:

• polls the open operations' Axis jobs every 2 seconds (the finished-job hint from Axis makes it faster), applies results to the mirror once, fails operations that never reached Axis within a minute (not_dispatched) or that Axis no longer knows (job_lost);
• starts each tenant's scheduled sync when it is due (checked every 30 seconds; the tenant's interval, default 30 minutes);
• purges finished operations and audit entries after their retention windows, and used step-up tokens.