Configuration#

Serverless ADR requires proper configuration to initialize its environment, connect to databases, manage media and static files, and control runtime behavior. This guide explains the key configuration parameters, environment variables, and recommended setup practices.

Overview#

Configuration for Serverless ADR can be done through:

  • Constructor parameters when instantiating the ADR class.

  • Environment variables (legacy or advanced usage).

  • Optional overrides during the setup() call.

Key Configuration Parameters#

The primary configuration options for the ADR class constructor are:

  • ansys_installation (str, optional): Path to the Ansys installation directory. Special value "docker" triggers Docker-based setup. Defaults to automatic detection if omitted.

  • ansys_version (int, optional): Specify the Ansys version explicitly. If not provided, automatic detection attempts to determine it.

  • db_directory (str, optional): Directory path for the SQLite database files. If omitted, must provide databases config or environment variable.

  • databases (dict, optional): Dictionary specifying multiple database configurations (e.g., for PostgreSQL or multi-DB setups). Requires a "default" database entry.

  • media_directory (str, optional): Directory path for media file storage (uploaded images, animations, etc.). Falls back to db_directory media subfolder if not set.

  • static_directory (str, optional): Directory path where static files (CSS, JS) will be collected.

  • media_url (str, optional): Relative URL prefix for serving media files. Must start and end with a forward slash (e.g., "/media/").

  • static_url (str, optional): Relative URL prefix for serving static files. Must start and end with a forward slash (e.g., "/static/").

  • debug (bool, optional): Enable or disable debug mode. Defaults to production mode if not set.

  • opts (dict, optional): Dictionary of environment variables to inject into the process environment.

  • logfile (str, optional): File path to write logs. If omitted, logs to console.

  • docker_image (str, optional): Docker image URL to use when ansys_installation="docker". Defaults to official Nexus image.

  • in_memory (bool, optional): Enables in-memory database and media storage for ephemeral or test usage.

Environment Variables#

Warning

Use of environment variables for Serverless ADR configuration is strongly discouraged. Environment variables represent a legacy configuration method and can lead to hidden, hard-to-debug issues, security risks (such as leaking secrets), and inconsistent behavior especially in multi-instance or containerized deployments.

It is highly recommended to use explicit constructor parameters and configuration files for all setup and runtime options instead.

Core Variables#

  • CEI_NEXUS_TIMEZONE Olson format timezone string for the server (e.g., America/New_York). Used in formatting timestamps in reports.

  • CEI_NEXUS_LOCAL_DB_DIR Filesystem path to the directory containing the SQLite database file(s). Alternative to configuring db_directory in code.

  • CEI_NEXUS_LOCAL_MEDIA_DIR Path to the media directory for uploaded files such as images and animations. Alternative to media_directory parameter.

  • CEI_NEXUS_MEDIA_URL_PREFIX URL prefix used to access media files remotely. Must start and end with a slash, e.g., /media/. Corresponds to the media_url constructor parameter.

Database Connection Variables#

  • CEI_NEXUS_DB_ENGINE Database engine. Defaults to SQLite.

  • CEI_NEXUS_DB_DATABASE_NAME Name of the database to connect to. Defaults to nexus_database.

  • CEI_NEXUS_DB_USER Database username. Default is nexus.

  • CEI_NEXUS_DB_PASSWORD Password for the database user. Default is cei.

  • CEI_NEXUS_DB_HOSTNAME Database server hostname or IP address. Defaults to the path to the SQLite database file.

  • CEI_NEXUS_DB_PORT Database server port number. Default is not set for SQLite.

Security Variables#

  • CEI_NEXUS_SECRET_KEY Django secret key used internally. If not provided, a built-in default key is used (not recommended for production).

Advanced / Optional Variables#

  • CEI_NEXUS_ENABLE_ACLS Enables per-category Access Control Lists (ACLs). Experimental and not recommended for general use.

Usage Notes#

  • Constructor parameters take precedence over environment variables. If both are set, constructor values will be used.

  • Always set secure secret keys in production environments to protect sensitive data. If you do not set a key, a default will be used.

Example: Setting environment variables in Linux shell:

export CEI_NEXUS_LOCAL_DB_DIR="/var/data/adr_db"
export CEI_NEXUS_LOCAL_MEDIA_DIR="/var/data/adr_media"
export CEI_NEXUS_MEDIA_URL_PREFIX="/media/"
export CEI_NEXUS_SECRET_KEY="a-very-secure-secret-key"

Example: Passing variables via opts parameter:

opts = {
    "CEI_NEXUS_LOCAL_DB_DIR": "/var/data/adr_db",
    "CEI_NEXUS_LOCAL_MEDIA_DIR": "/var/data/adr_media",
    "CEI_NEXUS_MEDIA_URL_PREFIX": "/media/",
    "CEI_NEXUS_SECRET_KEY": "a-very-secure-secret-key",
}

adr = ADR(ansys_installation="/opt/ansys", opts=opts)
adr.setup()

Note: Prefer constructor parameters for new projects. Environment variables remain supported primarily for legacy compatibility.

Best Practices#

  • Call ``ADR.setup()`` once per process early in your application lifecycle. This initializes environment, Django settings, and database migrations.

  • For multi-process setups (e.g., Gunicorn, multiprocessing), ensure each process calls ``setup()`` independently.

  • Within a process, all threads share the ADR configuration after setup; calling ``setup()`` multiple times per process is disallowed.

  • Configure ``media_url`` and ``static_url`` to match your web server routing to serve media and static content correctly.

  • Use absolute paths for all directory configurations to avoid ambiguity.

  • For Docker-based Ansys installations, provide a valid Docker image and ensure Docker is installed and running.

Examples#

Basic local SQLite setup with explicit directories:

from ansys.dynamicreporting.core.serverless import ADR

adr = ADR(
    ansys_installation=r"C:\Program Files\ANSYS Inc\v252",
    db_directory=r"C:\Reports\DB",
    media_directory=r"C:\Reports\Media",
    static_directory=r"C:\Reports\Static",
    media_url="/media/",
    static_url="/static/",
    debug=True,
)
adr.setup(collect_static=True)

Troubleshooting#

  • InvalidPath Error: Verify all configured directories exist and are accessible.

  • ImproperlyConfiguredError: Check database config dictionary and URL prefixes for correctness.

  • Docker Errors: Ensure Docker daemon is running and image URLs are valid.

  • Static files not found: Confirm collect_static=True was set during setup and that your web server serves the static directory correctly.

  • Media files missing: Verify media upload paths and web server routing for the media URL.

Summary#

Proper configuration of Serverless ADR ensures seamless database connections, media management, and web serving of report assets. Follow best practices for setup and environment initialization to avoid common issues.