Inventory File¶

VOR Stream deployments rely on an Ansible inventory file for site-specific customizations via host variables. This allows for customization of deployment locations, ports, users, etc. The default inventory file resides in the root-level directory and is named hosts.ini.

Defining Target Hosts¶

Single Machine Deployment¶

1. The first line under each host group in the hosts.ini file specifies a deployment target definition that identifies the machine on which VOR Stream is being deployed.
2. Save and close the hosts.ini file.

To assign a machine to a target host, specify a single hostname under all and it will cascade to the remaining hosts. An example is shown below.

[all]
hostname1

[compute]

[django]

[caddy]

[postgres]

[rabbitmq]

[super]

[web]

[sdk]

[vault]

[consul]

[consul_ui]

Save and close the hosts.ini file after editing.

Multi Machine Deployment¶

The first line under each host group in the hosts.ini file specifies a deployment target for each target machine.

To assign machines to target hosts, specify a hostname under each host group. Some services, e.g., Consul, support a clustered deployment where multiple hostnames can be specified. An example is shown below.

[all]

[compute]
hostname1

[django]
hostname2

[caddy]
hostname3

[postgres]
hostname4

[rabbitmq]
hostname5

[super]
hostname6

[web]
hostname7

[sdk]
hostname8

[vault]
hostname9

[consul]
hostname10
hostname11
hostname12

[consul_ui]
hostname13

Save and close the hosts.ini file after editing.

Variable Customizations¶

The sections below describe the inventory file variable customizations that are available to

Foundational¶

General¶

• use_become - True/False to use privilege escalation (defaults to True). If running with use_become=False, tasks that require elevated privileges must have been executed prior to running the playbook.
• environment_name - the name of the environment, e.g., dev, test, prod. Currently, this is only used if Sentry integration with Django/Super is enabled.
• vor_root - the root directory for the installation.
• vor_user - the user to perform the installation. Created if it does not exist (requires root).
• vor_group - the primary group for vor_user. Created if it does not exist (requires root).
• supervisord_root_deployment - True/False to allow for running services as root, e.g., to run a service on a privileged port. Requires root if True.
• create_system_profile_script - True/False to create the system profile script (defaults to True). If True, the Ansible deployment will attempt to create the system profile script under /etc/profile.d. The script will always exist at {{ vor_root }}/etc/profile.d as well. If running with use_become=False, the script can be manually copied from {{ vor_root }}/etc/profile.d to /etc/profile.d for automatic sourcing of all users on the system.
• vor_stream_profile_script_name - name of the script, e.g., vor-stream to create under /etc/profile.d to set important environment variables for the installation. Requires root.
• vor_log_directory - directory to store log files
• vor_user_max_open_files - the open file descriptor (nofile) limit applied to vor_user via /etc/security/limits.d/99-vor-nofile.conf (defaults to 65536). RabbitMQ and other supervisord-managed services inherit this limit; the RHEL default of 1024 is too low and can exhaust descriptors under load. No further tuning is needed at 65536, but raising it well beyond that also means raising Erlang's port ceiling (ERL_MAX_PORTS) for RabbitMQ, which would otherwise become the new bottleneck. The limits file is only written when running with use_become=True, and only in a non-root deployment; see File Descriptor Limits for the cases where it is skipped and how the limit applies.
• Python_version - the version of Python to install (do not modify). Python is compiled and installed on all hosts.
• vault_addr - the address of the Vault server that the deployment should use. This defaults to hostname of the first Vault host in the inventory file.
• vault_skip_verify - skip verifying the TLS certificate of the Vault server (defaults to False). This is useful for performing deployments where the Vault server's certificates are: self-signed, signed by an internal CA, or signed by a CA that is not trusted by the deployment machine. This can also be set when replacing expired Vault certificates.
• oidc_providers_file - the path to the OIDC providers file. This file is used to configure the OIDC providers in VOR. This defaults to {{ inventory_dir }}/oidc_providers.yaml'.
• vor_token_ttl - the TTL for the VOR token in seconds (defaults to 43200). A job's nodes call Super, the SDK API and Django with the token of the user who started the job, and all three refuse it once it expires. A job still running at that point loses those calls: signals, dynamic facts, log lines and final statistics no longer reach Super, so a node waiting on a signal waits until the job is stopped. A job started from the web interface may start with a token up to an hour old, so at the default it can count on about 11 hours. Increase this value if you have jobs that are expected to run longer than that. The key that signs the tokens rotates on the same period and stays available for checking twice as long, so no token outlives its key.
• default_sql_version - System-wide setting for the default SQL syntax version to use. This can be overridden at the process and node level. Acceptable values are 1 and 2.
• database_conn_path - System-wide setting for the Vault path (relative to kv/data/node) where database connection information is stored. When set, all database nodes will use this path to retrieve their connection details by default. For example, if the full Vault path is kv/data/node/vor/mssql, set this variable to vor/mssql. This setting can be overridden at the playpen or node level for more granular control.
• web_server_name - the hostname to use for the web server (defaults to the fully qualified domain name of the web host). If a user-facing reverse proxy is configured in front of the web server, then this can be set to DNS name of the reverse proxy.
• web_port - the port to use for the web server (defaults to 8080).
• web_ssl_port - the port to use for the web TLS server (defaults to 8081).
• supervisord_web_port - the port for the Supervisord web interface (defaults to 9001).

LDAP¶

If you choose to use LDAP for authentication, the following variables are required for Vault to configure the LDAP authentication method:

• ldap_base_dn
• ldap_bind_dn
• ldap_bind_password
• ldap_group_search
• ldap_group_attr
• ldap_host - the hostname of the LDAP server.
• ldap_protocol - the protocol to use for the LDAP server. Acceptable values are ldap and ldaps.
• ldap_group_subtree
• ldap_user_attr

Database¶

• database_type - the type of database to use for the Django backend. Acceptable values are postgres and mssql (defaults to postgres).
• database_user - the user to authenticate as when connecting to the database.
• database_password - the password for the user. To change it after deployment, see Changing Stored Passwords.
• database_vault_user - the name of the PostgreSQL role Vault's database secrets engine signs in as to issue Django's dynamic credentials (defaults to database_user with a _vault suffix). Set it only to avoid a name collision. Applies to PostgreSQL 16 and later with dynamic secrets; see the note below.
• database_vault_password - only used for PostgreSQL dynamic credentials. Leave it blank on managed installations; the Django play generates the initial password for database_vault_user. Set it for initial Vault configuration on an unmanaged server. Reruns preserve Vault's password.
• database_schema - the schema to use for the database (defaults to django).
• database_host - The hostname of the database server (defaults to the first host in the "postgres" Ansible group if using PostgreSQL and localhost if using MSSQL).
• database_port - The port of the database server (defaults to 1433 for MSSQL and 5432 for PostgreSQL).
• database_name - the name of the database to use (defaults to vor).
• database_sslmode - disable/require (defaults to require). Only applicable to PostgreSQL.
• postgresql_allow_major_upgrade - True/False to authorize the automated PostgreSQL 14 to 18 copy-mode migration (defaults to False). Leave this disabled for ordinary deployments. Enable it only after taking a backup and scheduling a maintenance window.
• database_vault_path - path to the Vault service that should be used to retrieve the database credentials. To use dynamic secrets, use database/creds/vor-django-role for PostgreSQL (dynamic credentials with Microsoft SQL Server are not supported at this time). If the dynamic secrets engine is used, the database_user and database_password parameters should also be set to create the dynamic roles.

CREATE ROLE vpsql_vault WITH LOGIN CREATEROLE INHERIT PASSWORD 'your-password';
GRANT vpsql TO vpsql_vault WITH ADMIN OPTION, INHERIT FALSE, SET FALSE;

• mssql_driver - the driver to use for the MSSQL database (defaults to ODBC Driver 18 for SQL Server).
• mssql_extra_params - extra parameters to pass to the MSSQL database (defaults to 'Encrypt=no;LongAsMax=yes'). See Supported DSN/Connection String Keywords and Connection Attributes for a list of supported keywords.

RabbitMQ¶

• rabbitmq_host - the hostname of the RabbitMQ server. In a production environment, this should be a load balancer or other proxy that can route messages to the RabbitMQ cluster, as this value is used by Vault for RabbitMQ secret creation and by Consul for health checks. If using a managed service RabbitMQ, e.g., Amazon MQ for RabbitMQ, this should be the address to that managed instance. If RabbitMQ is installed by Ansible and this value is not provided, it will default to the inventory hostname of the first RabbitMQ node in the cluster. If RabbitMQ is not installed, it's mandatory to set this variable.
• rabbitmq_user - the user to authenticate as when connecting to the RabbitMQ server. If RabbitMQ is installed by Ansible, the user will be created if it does not exist. If RabbitMQ is not installed, it's mandatory to set this value.
• rabbitmq_password - the password for the user. To change it after deployment, see Changing Stored Passwords.
• rabbitmq_amqp_port - the port of the RabbitMQ server (defaults to 5672).
• rabbitmq_management_port - the port of the RabbitMQ management interface (defaults to 15672).
• rabbitmq_vhost - the virtual host to use (defaults to /).
• rabbitmq_node_name - the name of the node to use (defaults to rabbit).
• rabbitmq_vault_path - Vault path to retrieve RabbitMQ credentials from. To use the Vault key-value secrets engine (static credentials), specify the path in the form of kv/data/<name>, e.g., kv/data/rabbitmq. To use the dynamic secrets engine, specify the path in form of rabbitmq/creds/<credential-name> e.g., rabbitmq/creds/vor-midtier-role. If using the dynamic secrets engine, the values provided for rabbitmq_user and rabbitmq_password are used by Vault to communicate with RabbitMQ to generate credentials.

Email Server¶

• email_port - port that the email server should listen on. (defaults to 587)
• email_host - hostname that the email server should listen on. (e.g. if using Amazon SES, the domain name will look like email-smtp.us-east-1.amazonaws.com)
• email_sender - email address that the email server should use as the sender address.
• email_user - user that the email server should authenticate as.
• email_password - password that the email server should use to authenticate.
• email_vault_path - path to the Vault service that should be used to retrieve the email server credentials.

TLS¶

To copy certificate from the local machine to the server, use the following variables:

• local_tls_ca_cert_file_path - path to the local TLS CA certificate file.
• local_tls_cert_file_path - path to the local TLS certificate file.
• local_tls_key_file_path - path to the local TLS key file.

Set the following variables to the paths to the files on the server to indicate the server should be configured to use TLS:

• tls_directory - path to the directory where the TLS files should be stored.
• tls_ca_cert_file_path - path to the TLS CA certificate file.
• tls_cert_file_path - path to the TLS certificate file.
• tls_key_file_path - path to the TLS key file.

Vault¶

• vault_storage_path - path to store the Vault tokens and keys (defaults to <vor_root>/vault/data)
• vault_listener_address - used to set Vault's api_addr property. This defaults to the server's hostname and port 8200. This can be customized to a more generic address, e.g., 0.0.0.0:8200, to allow Vault to listen on all interfaces or using a go-sockaddr template, e.g., {% raw %}{{ GetInterfaceIP "eth0" }}:8200{% endraw %}. If this address is not an explicit IP address or hostname, the service_address variable must be set.
• vault_cluster_address - used to set Vault's cluster_addr property and generally does not require modification.
• vault_enable_audit - True/False to enable detailed logging of all requests and response to Vault (defaults to False).
• service_address - the address to register with Consul for the Vault service. This defaults to the value of vault_listener_address if it is an explicit IP address or hostname. Set this to the address only without the port. This can also be used to set the address to a load balancer in front of a Vault cluster if it is desired to send all traffic through the load balancer.
• vault_issuer - used for verifying JWTs issued by Vault. This should be set to an externally accessible address for Vault, e.g., https://vault.example.com:8200. In a clustered deployment, this would typically be a load balancer in front of the cluster. If not specified, this defaults to the listener address of the first node in the vault Ansible group.
• vault_cacert - path to a PEM-encoded CA certificate file used to verify the Vault server's TLS certificate. When set, this is configured as VAULT_CACERT in the environment for Django, Super, SDK, and the system profile.
• vault_namespace - the Vault namespace to use. When set, this is configured as VAULT_NAMESPACE in the environment for Django, Super, SDK, and the Vault agent. Only applicable to Vault Enterprise.

Consul¶

• consul_bind_addr - the address to bind for internal cluster communications (defaults to 0.0.0.0). If multiple private IPs are available, the address can be dynamically defined using a go-sockaddr template, e.g., {% raw %}{{ GetInterfaceIP "eth0" }}{% endraw %} (see Consul documentation for more information).
• consul_client_addr - the address to which Consul will bind client interfaces, including the HTTP and DNS servers (defaults to 127.0.0.1). Note that this value is not applicable to the Consul UI instance, which is always bound to 0.0.0.0.
• consul_http_api_port - the port of the Consul HTTP API (defaults to 8501).
• consul_http_max_conns_per_client - the maximum number of connections per client (defaults to the minimum of 10000 or the maximum number of file descriptors for the vor_user user minus 20). See Consul documentation for more information.
• consul_storage_path - path to store the Consul tokens and state.
• consul_server_rejoin_max_age - the maximum allowable downtime for a server before attempting to rejoin a cluster (defaults to 168h). See Consul documentation for more information.
• consul_dns_port - the port for the Consul DNS server (defaults to 8600).
• consul_server_rpc_port - the port for Consul server RPC communication (defaults to 8300).
• consul_serf_lan_port - the port for Consul Serf LAN gossip (defaults to 8301).
• consul_serf_wan_port - the port for Consul Serf WAN gossip (defaults to 8302).

Cloudwatch¶

• collection_interval - the interval in seconds to collect all metrics (defaults to 60).
• cpu_collection_interval - the interval in seconds to collect CPU metrics (defaults to 60).
• disk_collection_interval - the interval in seconds to collect Disk metrics (defaults to 60).
• memory_collection_interval - the interval in seconds to collect Memory metrics (defaults to 60).
• ignored_mounts - comma-separated list of mount points to ignore when collecting disk metrics (defaults to ["/boot", "/boot/efi"]).

Service group level configuration¶

Caddy¶

• caddy_version - the version of Caddy to install (do not modify).

Django¶

• default_require_comment - True/False to enable/disable comment prompts when saving objects in the UI (defaults to True). This setting can be modified at the playpen level by updating the require_comment field in the playpen configuration.
• default_require_upload_approval - True/False to enable/disable the requirement for uploaded files to be approved by a manager (defaults to False). This setting can be modified at the playpen level by updating the require_upload_approval field in the playpen configuration. When set to True only approved uploads (ex/ Macro Economic Scenarios, Portfolio Data, Overlays) will be available for selection on the View Scenario, Build Study and Run Study screens.
• default_disable_scenario_weighting - True/False to enable/disable scenario weight prompting when attaching them to studies.
• default_require_methodology_selection - True/False setting to true will force users to select a methodology before saving a study.
• default_require_scenario_selection - True/False setting to true will force users to select scenarios before saving a study.
• default_hide_scenario_selection - True/False setting to true will hide the scenario tab from the build study screen.
• default_disable_model_unit_test - True/False setting to true will hide the model run section from the model screen.
• django_server_name - the server name to use for the Django server (defaults to the group hostname).
• django_debug - True/False to enable/disable Django's DEBUG setting (defaults to False).
• django_sentry_dsn - if using Sentry with Django, the Sentry DSN to use for error reporting (defaults to None). If this value is not set, the Sentry SDK will not be configured.
• django_port - the port to use for the Django server (defaults to 8000).
• django_ssl_port - the port to use for the Django TLS server (defaults to 8001).
• superuser_username - the username to use for the superuser (defaults to vrisk).
• superuser_email - the email address to use for the superuser (defaults to [email protected]).
• django_vault_roleid_path - path to the approle id for authenticating to Vault.
• django_vault_secretid_path - path to the secret id for the approle.
• django_vault_token_path - path to the Vault token to retrieve credentials for the django service.
• data_upload_max_memory_size - the maximum allowed size of a request body in bytes. This setting is disabled by default. See Django documentation for more information.
• uwsgi_limit_as - the maximum amount of virtual memory (in bytes) that a uWSGI worker can use (defaults to 2048). See the uWSGI documentation for more details.
• uwsgi_listen - the maximum number of pending connections for the uWSGI server (defaults to the kernel setting for the maximum listen backlog, which can be viewed by running the sysctl net.core.somaxconn command). See the uWSGI documentation for more details.
• uwsgi_max_temp_file_size - This value is used to disable the download button on the waterways outputs modal for files larger than the max temp file size.
• uwsgi_read_timeout - the maximum amount of time in seconds to wait for a request from uWSGI (defaults to 60).This sets the timeout value for uWSGI harakiri options.
• django_super_request_timeout - timeout in seconds for requests made from Django to the Super service (defaults to 10).

• django_fixtures - space-separated fixtures to load during deployment. Defaults to auth filter_type script_syntax help_docs patch_notes llm. In environments with custom auth/group permission models, you can omit auth and supply your own fixture strategy. If this resolves to an empty value, fixture loading is skipped. An override replaces the entire default list, so include all the entries you still want. For example, set django_fixtures to auth filter_type script_syntax help_docs patch_notes llm upload_type to include sample upload type definitions.

  Keep llm when Digital Teams is deployed

  llm is the VOR Digital Teams model catalog. An override that drops it deploys Digital Teams with an empty model list, so a deployment that populates the [ai] group refuses to run without it.

  • django_force_script_name - sets Django's FORCE_SCRIPT_NAME setting. Use this when Django is served behind a reverse proxy under a subpath, e.g., /django.
  • django_secure_proxy_ssl_header - sets Django's SECURE_PROXY_SSL_HEADER setting. Use this when Django is behind a TLS-terminating reverse proxy.
  • csrf_trusted_origins - comma-separated list of trusted origins for Django CSRF protection. See Django's CSRF_TRUSTED_ORIGINS documentation for more information.
  • oidc_config_vault_path - the Vault path where OIDC provider configuration is stored (defaults to kv/data/oidc-config).

Compute¶

• compute_port - the port to use for the compute server SSHD service (defaults to 23234).
• go_version - the version of Go to install (do not modify).
• go_checksum - the checksum of the Go binary to download (do not modify).

RabbitMQ¶

See RabbitMQ in Production for tuning guidance on these settings.

• consumer_timeout - delivery acknowledgement timeout in milliseconds (defaults to 1800000). See the RabbitMQ documentation for more information.
• disk_free_limit_absolute - sets disk_free_limit.absolute (defaults to 2GB). See the RabbitMQ documentation. Ignored when disk_free_limit_relative is set.
• disk_free_limit_relative - sets disk_free_limit.relative (unset by default, leaving the 2GB absolute floor above). See the RabbitMQ documentation. Takes precedence over disk_free_limit_absolute when both are set. An empty value counts as unset.
• vm_memory_high_watermark_absolute - sets vm_memory_high_watermark.absolute (unset by default, leaving RabbitMQ's own relative default, which is within the recommended 0.4-0.7 range). See the RabbitMQ documentation. Ignored when vm_memory_high_watermark_relative is set.
• vm_memory_high_watermark_relative - sets vm_memory_high_watermark.relative (unset by default, as above). See the RabbitMQ documentation. Takes precedence over vm_memory_high_watermark_absolute when both are set. An empty value counts as unset.

Super¶

• super_docs_dir - directory to store symlinks to playpen documentation (defaults to <vor_root>/docs/playpen).
• super_queue_buffer_length - queue buffer length (defaults to 50).
• super_queue_prefetch - queue prefetch count (defaults to 10).
• super_queue_threads - number of threads to use for the queue (defaults to 0, which will use the number of CPUs available on the Super host).
• super_queue_limit - Maximum number of observation waiting on a queue (defaults to 0, which implies no limit).
• super_queue_limit_wait - The number of milliseconds between polling for current queue length (defaults to 10). Only relevent if there is a queue limit.
• super_playpen_upgrade_enabled - True/False to enable/disable the auto-upgrade playpen feature (defaults to True).
• super_logs_dir - directory to store operation logs for the Super service (defaults to <vor_log_directory>/super).
• super_user_groups_cache_ttl - TTL for the django group cache(defaults to 60s).
• super_django_request_timeout - timeout for django requests (defaults to 60s).
• super_node_http_timeout - request timeout for REST calls from process nodes to the Super API, e.g., 30s. Super passes this value to node processes when it runs a process. Useful when a slow or heavily loaded server causes node requests to time out prematurely. If unset, Python nodes default to 10s and Go nodes use no timeout.
• super_python_command_timeout - inactivity timeout for the Python node command-queue consumer loop, e.g., 5s. Super passes this value to node processes when it runs a process (defaults to 1s, Python nodes only).
• super_request_log_exclude - list of request paths the Super API leaves out of its request trace logs, e.g., ["/rest/version", "/rest/playpen"]. Each entry is matched against the full request path exactly, so a path the Super API does not serve is silently ignored. Excluded paths still receive an X-Request-ID response header, but do not log request start and completion (defaults to ["/rest/version"]; set [] to log every path).
• super_vault_roleid_path - the path to the approle id for authenticating to Vault.
• super_vault_secretid_path - the path to the secret id for the approle.
• super_vault_token_path - path to the Vault token to retrieve credentials for the super service.
• umask - the umask to use for the super service (defaults to 002. This allows the playpen owner and group members to overwrite files created by the Super API).
• envvars - comma-separated list of environment variables for the super service to run with, e.g., ENVVAR1=value-1,ENVVAR2=value-2,...,ENVVARN=value-n.
• super_listen_addr - host and port to listen on. Left unset, Super listens on <super-hostname>:1962. Setting a value without a port changes the default from 1962 to 443 or 80 according to the scheme. An https scheme enables Super's TLS regardless of the tls_* variables. Super registers this host name in Consul for other hosts to connect to. In a multi-host deployment, use a name that those hosts can resolve; a local bind address will not work.
• log_level - the log level to use for the super service. Available levels are trace, debug, info, warning, error, fatal and panic (defaults to trace).
• super_sentry_dsn - if using Sentry with Super, the Sentry DSN to use for error reporting (defaults to None). If this value is not set, the Sentry SDK will not be configured.
• super_sentry_traces_sample_rate - the sample rate to use for tracing with Super. This should be a value between 0 and 1. If this value is not set, tracing will not be enabled. See Set Up Tracing for more information.
• super_pprof - True/False. Enables the debugging profiler in the super service. Defaults to false.
• ha_mode - True/False to enable high-availability mode for the Super service. Defaults to True if more than one host is in the super Ansible group, False otherwise.

Web¶

• enable_reporting_db - true/false feature flag to enable the option to save results to the reporting database on the model tab (defaults to false).
• django_endpoint - the endpoint to communicate with the Django server. The format is //<django-server-name>:<django-port>.
• django_ssl_endpoint - the TLS endpoint to communicate with the Django server. The format is //<django-server-name>:<django-ssl-port>.
• consul_endpoint - the endpoint to communicate with the Consul API. This should be an endpoint accessible from the UI, such as the Consul host or a load balancer or proxy pointing to a Consul host or cluster. The format is <scheme>//<hostname>:<port>, where <port> and scheme scheme are optional. If scheme is not provided it will default to the scheme of the web UI.
• local_logo_file_path - specify a path to a logo file on the Ansible controller to override the default logo for the web UI.
• primary_color - override the website's primary color.
• accent_color - override the website's accent color.
• syncfusion_license_key - the Syncfusion license key.
• angular_production_flag - true/false to enable/disable Angular production mode (defaults to true). Set to false for development builds with additional debugging information.

SDK¶

• sdk_listen_addr - host and port to listen on (defaults to <sdk-hostname>:9000).
• sdk_django_request_timeout - timeout for django requests (defaults to 60s).
• sdk_vault_roleid_path - path to the approle id for authenticating to Vault.
• sdk_vault_secretid_path - path to the secret id for the approle.
• sdk_vault_token_path - path to the Vault token to retrieve credentials for the SDK service.
• log_level - the log level to use for the SDK service. Available levels are trace, debug, info, warning, error, fatal and panic (defaults to debug). Use trace to enable gRPC payload logging.

Vault¶

• vault_listener_address - address of the Vault server (defaults to hostname where the Vault server is running at port 8200).
• vault_cluster_address - address (full URL) that is shown to other Vault servers for request forwarding (defaults to hostname where the Vault server is running at port 8201).

Consul¶

• encryption_key - key to encrypt communication among Consul agents within a datacenter. (see Consul Gossip Encryption documentation for more information)
• consul_ca_cert - Consul CA certificate file. Create one for each installation, as described in Replacing the CA. The deployment signs each host's Consul certificates with it; to renew those, see Rotating Consul TLS Certificates.
• consul_ca_key - Consul CA key.

Consul UI¶

• consul_ui_http_api_port - the port of the Consul UI HTTP API (defaults to 8500).

Digital Teams ([ai])¶

Digital Teams is disabled by default. To install and enable it:

1. Add one host to the [ai] group in hosts.ini (it may co-locate with the web or django host).
2. Set ai_streaming_service_token to a unique secret in [all:vars], since the django play and the ai_service role both read it. It is shared by Django (AI_STREAMING_SERVICE_TOKEN) and ai-service (AI_SERVICE_TOKEN); the deploy fails fast if it is unset or left at the development default.
3. Populate both [django] and [super]. The role reads each upstream's CA bundle from those hosts' inventory variables, and the deploy stops if either group is empty.

Removing the host from [ai] and running the playbook again removes the Digital Teams route and its sidebar entry. The ai-service files stay on the host. To uninstall them, remove <vor_root>/etc/supervisord.d/ai-service.ini, <vor_root>/etc/consul.d/ai.hcl, <vor_root>/etc/ai-service/, <vor_root>/ai-service/ (source, virtual environment, session files and user skills) and <vor_log_directory>/ai-service, then reload supervisord and Consul. Conversation history stays in the Django database.

Optional per-host variables:

• ai_service_port (default 8002).
• ai_server_name: the name Consul registers for the host and checks /healthz against (defaults to the host's fully qualified domain name). Set it when that name does not resolve from the web host.
• aws_access_key_id / aws_secret_access_key: static AWS credentials for Bedrock. When unset, ambient credentials (instance profile) are used.
• aws_session_token: for temporary or SSO-issued credentials, set alongside the access key and secret. These expire, and Digital Teams cannot call Bedrock once they do until the playbook runs again with new ones. Prefer an instance profile in production.
• ai_service_model_region: the AWS region Digital Teams sends Bedrock and Bedrock Mantle requests to (default us-east-1). The shipped catalog's us. model IDs are US cross-region inference profiles, so they work only when this is a US region.
• ai_service_model_id: the model ai-service falls back to when the llm catalog offers none (default us.anthropic.claude-haiku-5-5). It does not change the model new conversations start on, which comes from the catalog.

Optional [all:vars] settings. Django and ai-service both read the first two; Django alone reads the host list:

• ai_allowed_providers: a comma-separated list of the model providers Digital Teams may use, from aws, mantle and vllm. Empty (the default) allows all three. When it is set, Digital Teams offers only the listed providers' models and takes its helper and title models from them, so at least one listed provider needs enabled models; for vllm, that means a registered vLLM server.
• ai_vllm_api_key: the API key your vLLM servers expect (their --api-key). Leave it unset for servers started without one. When it is set, Digital Teams sends it to every registered vLLM server, so a new server can be registered only if its host is listed in ai_vllm_endpoint_allowed_hosts. A server registered before the key was set stays registered but reads as unavailable until its host is listed too.
• ai_vllm_endpoint_allowed_hosts: a comma-separated list of the vLLM server hostnames that may be registered while ai_vllm_api_key is set.