FAQ

Installation and startup

docker compose up reports required variable … is missing

A required .env entry is missing. deploy.sh generates all of them. For a manual installation, complete .env against the configuration reference; RST_USER_DB_PASSWORD and CADDY_SITE_ADDRESS are the usual gaps.

https://<hostname>/v2/ does not open

Run docker compose -f docker-compose.prod.yml logs caddy gateway. Either port 443 is closed (open it in the cloud security group), or CADDY_SITE_ADDRESS is a bare IP and the TLS handshake fails; use a hostname and add a hosts entry.

readyz returns not_ready, or es_write is denied

If the es field is not ok, the gateway cannot reach Elasticsearch; check the URL, certificate, and network. If es_write is denied, the account cannot create or write .rst_copilot_* indices; grant the privileges in Elasticsearch permissions.

Gateway log shows /app/state is not writable by uid 10001

The state volume is not owned by uid 10001 and the entrypoint could not fix it. Run docker run --rm -v <volume>:/s alpine chown -R 10001:10001 /s and restart the gateway.

Sign-in

"This deployment still uses the shipped default password, so remote sign-in is refused."

RST_ADMIN_PASSWORD_HASH is not set. deploy.sh sets it; for a manual installation see Installing from the archive. An isolated lab can set RST_ALLOW_DEFAULT_PASSWORD=1.

RST_ADMIN_PASSWORD_HASH is set, but sign-in is still refused

Compose expanded the $ characters in the hash as variables. Write every $ as $$ in .env.

The Users page reports no separate user table

RST_USER_DB_URL is not set. deploy.sh sets it and starts userdb; for a manual installation see Users and roles.

A user keeps working with their old role

A role change applies immediately but does not end the session; the interface updates when the user refreshes the page. To sign the user out at once, select Disable.

Ask AI

The query fails or returns nothing

The result card usually states the cause and offers a next step; see Empty results. If it does not, check that the index is in the allowlist and that the model key and endpoint are correct.

"Index … is not in the configured whitelist"

The index matches no pattern in RST_INDEX_WHITELIST. An administrator adds the pattern under Index allowlist in Settings.

"today" or "yesterday" returns nothing or the wrong day

RST_TIMEZONE is not set, so the gateway splits days at UTC. Set it to your offset, for example +08:00.

"The model thought for over 45s without starting an answer, so it was stopped."

The model endpoint is congested, or a thinking model reasons too long. In AI settings, set Reasoning for that provider to Off or Low, or add a fallback provider. RST_LLM_FIRST_TOKEN_TIMEOUT_S sets the limit.

The same question gives a different answer the second time

Follow-up questions in a conversation carry the previous turn's index and references. To ask without that context, select New conversation first.

License

activation limit reached

Every host seat on the license is in use. On the old host, open License and select Deactivate this license, then activate on the new host.

Offline license is bound to a different host

The fingerprint in the .lic file does not match this host. Either state/machine-id or state/server_guid was regenerated, or the file was issued for another host.

"Cannot read this machine’s hardware identity"

The container cannot read /etc/machine-id. Either state/machine-id is not mounted (a missing file makes docker mount a directory) or its mode is not 644.

An online license is activated, but the paid features stay locked

The paid engines unlock after the first successful heartbeat, which is retried every 5 minutes on failure. Check Last heartbeat on the License page.

License state is "In grace period" or "Heartbeat lost"

The gateway cannot reach license.reallysec.com:443. Check outbound access. If the connection stays down past the offline grace period, the license lapses.

Alerts and triage

Alerts stays at 0

The index in RST_ALERT_INGEST_INDEX has no new alerts, or ES_USER cannot read .alerts-security.alerts-*. Search the gateway log for alert_ingest. When ingest first starts, it looks back 1 hour by default; RST_ALERT_INGEST_LOOKBACK widens that window.

"Scoring did not complete."

The model call timed out. Lower Maximum clusters sent to the model (default 30; 10 usually works) or raise the provider timeout.

Triage pulls only a few alerts

Time window (minutes) defaults to 60. Raise it, up to 10080 (7 days).

Knowledge base

"Runbooks are off"

No embedding model is configured. Test and save one under AI settings.

Saving the embedding model is refused because of a dimension mismatch

The new model's dimension differs from the existing .rst_copilot_kb index. Switch back to the original model, or delete .rst_copilot_kb and upload the documents again.

Notifications

An email destination stays at "Will retry" or "Given up"

Read the last error in the delivery log. The usual causes are no mail server configured, a wrong password, or a blocked SMTP port. After fixing it, select Resend.

A destination is marked "Secret invalid"

After a gateway reinstall, the old ciphertext cannot be decrypted. Edit the destination and enter the webhook URL and secret again.

Updates

Something breaks after an update

Run sudo ./deploy/rst-update.sh --rollback to return to the previous version, or set GATEWAY_IMAGE_TAG back to the previous version and restart.

Contact support

Run docker compose -f docker-compose.prod.yml logs --since 30m gateway > gateway.log and send gateway.log with the readyz output to support@reallysec.com. The gateway log contains no business log data or secrets.