On this page

Self-hosting Guide

Installation and operations for authorized Aevyra administrators.

Self-hosting prerequisites

Obtain the complete authorized release and its deployment configuration instructions. A source-review export is not an installable distribution: it can omit required configuration, assets, dependencies, and services.

Prepare:

A maintained server operating system and Python 3.10 or later for the base runtime.
A dedicated service account and persistent storage with restricted permissions.
An HTTPS hostname, valid TLS certificate, and reverse proxy or load balancer.
The database, queue, Redis, and evidence-storage services required by your deployment profile.
Approved secret management and the required identity-provider or connector registrations.
Monitoring, backup storage, and a tested recovery procedure.

The bundled enterprise SSO runtime installer specifically requires Linux x86-64, Python 3.12, /usr/bin/xmlsec1 with its OpenSSL backend, and the supplied verified offline SSO wheelhouse. This is a narrower requirement than the base Python runtime.

Capacity depends on selected services, evidence volume, and concurrent assessments. Validate sizing with representative authorized workloads before production use.

Install the runtime

Run from the complete release directory. The following installs the base environment; it does not provision production databases, identity registrations, proxy configuration, or application services.

bash scripts/install.sh
source .venv/bin/activate

For deployments using the optional connectors:

CRYPTO_AGILITY_INSTALL_CONNECTORS=1 bash scripts/install.sh

For deployments requiring the bundled enterprise SSO runtime, first meet its platform prerequisites, then use a Python 3.12 interpreter:

PYTHON=python3.12 CRYPTO_AGILITY_INSTALL_SSO=1 bash scripts/install.sh

Use the release's deployment instructions to configure and supervise the API and evidence worker. Both must use the intended environment and compatible release. Installing dependencies alone does not enable asynchronous collection.

Configure production services

Keep credentials in protected service environment files or an approved secret manager. Keep passwords, private keys, API keys, connector tokens, and webhook signing secrets out of browser assets, deployment exports, reports, and source control.

Use the supplied configuration profile for persistent state and evidence storage. The launcher checks for required production backends and can refuse startup when development-only stores are selected. Resolve the reported configuration requirement rather than bypassing it for a public deployment.

For Microsoft connections, configure the approved application registration, callback URL, certificate credentials, SQL connection storage, and Redis authorization transaction storage required by the release. SSO login permission and evidence-collection permission are separate approvals.

Configure SMTP if using mailbox verification or password recovery. Configure billing only where your deployment requires it. Keep test and live billing environments separate.

Network and startup

Serve the web application and its /v1/ API through the configured HTTPS origin. Keep the application listener private. The default listener is 127.0.0.1:8443 and uses HTTP behind TLS termination; the port number does not imply HTTPS.

With production configuration already loaded into the service environment, the API entry point is:

.venv/bin/python scripts/run-control-plane.py

For a deployment using the default local listener, check basic API reachability with:

curl --fail http://127.0.0.1:8443/v1/health

Do not expose local setup wizards or worker validation probes publicly. If your deployment uses the separate local setup workflow, launch it with the installed interpreter:

PYTHON="$PWD/.venv/bin/python" bash scripts/setup-client-web.sh

This local setup tool is separate from the hosted customer application. Follow the release-specific instructions for generated configuration, worker enrollment, signing, and verification where required.

Validate before onboarding users

Verify HTTPS access, the correct workspace after login, email verification/recovery where enabled, approved connector consent, worker operation, and a representative evidence collection followed by report generation. Review the report's scope and unknowns.

Test that unapproved access is rejected. Confirm backup recovery and monitoring. Rehearse paid billing in an isolated test deployment where applicable; live Checkout creates a real subscription and charge.

The basic health endpoint reports API availability. The local health script checks Python and required directories:

.venv/bin/python scripts/health-check.py

Neither check alone proves that the database, worker, identity provider, email, connectors, or end-to-end reporting are working.

Operate, update, and recover

Monitor service availability, failed collection jobs, authentication errors, storage capacity, email delivery, backup failures, and credential/certificate expiry. Protect logs and avoid recording secrets or complete evidence payloads.

Back up all persistent state required by your deployment, including application configuration, databases, evidence storage, and necessary recovery material. Protect recovery keys separately under your secret-management policy. A filesystem backup alone may not cover external services. Regularly restore into an isolated environment and verify usability.

Before an update, record the current release and take a verified backup. Install the approved release into a separate directory or environment, validate configuration compatibility and end-to-end behavior, then switch the supervised services. Retain the previous release and a compatible recovery point. Dependency installation alone is not a complete application upgrade.

Set explicit retention policies for evidence, reports, and audit records. Log or demonstration cleanup settings do not automatically define customer evidence retention. Preserve records needed for incident response or legal requirements.

Troubleshooting

Symptom	First checks
Verification or recovery email does not arrive	Check spam, the supplied address, SMTP configuration, and delivery failures.
SSO fails	Check provider configuration, callback URL, domain setup, certificate validity, and the enabled SSO runtime.
Connection succeeds but collection fails	Review selected scope, read permissions, service availability, job status, and worker logs. Login alone is not evidence.
Website checks are unavailable	Check the authorized domain, public DNS, reachability, and the reported collection error.
Report coverage is low	Review unknown or unsupported checks and add approved evidence sources where available.
Collection is blocked after payment	Refresh subscription status and review payment confirmation and workspace allowances.
API refuses startup	Read the configuration error and verify production backends, secret access, and required dependencies.
API is reachable but jobs remain pending	Check the evidence worker and its queue/storage configuration.

When requesting support, include the release version, time of failure, affected workflow, job or assessment reference, and sanitized error message. Remove credentials, personal data, customer evidence payloads, and private configuration before sharing diagnostics.

Distribution and licensing

Use Aevyra under the license and agreement supplied with your authorized distribution. Consult those terms for installation, permitted use, redistribution, and support obligations. This README does not grant additional rights or disclose the proprietary assessment implementation.