Ansys Dynamic Reporting Launcher Command Line#

The Ansys Dynamic Reporting launcher application has a complete command line interface. This interface can be used to create a new database as well as configure and launch a dedicated ADR server instance. The command line greatly simplifies the creation and maintenance of ADR instances located on remote server with no native GUI interfaces (e.g. AWS or Azure servers).

Introduction#

The command line closely follows the GUI interface. The entire interface can be a bit daunting, but is can be viewed using the -h option:

C:> adr_launcher.bat -h

Operations#

There are two required command line arguments, the location of the database and the operation to be taken. Additional command line arguments can be used to specify specific server configuration options. All commands require that the --db_directory command line option be specified. This must be the name of the directory where the Ansys Dynamic Reporting database was (or is to be) created. Every operation (except create) begins by reading the configuration settings from the 'nexus.conf' file in the database directory. Next, the tool uses command line options to override various settings. For example '--instance_count 2' would change the number of server instances (for parallel report generator) to 2 from whatever had been set in the nexus.conf file. At that point, the tool will perform one of several operations using the augmented configuration options.

Potential actions include:

  • create - create a new database

    This is the only operation that does not read the nexus.conf file. In fact it requires that the target directory be empty. The operation will create a new, empty Ansys Dynamic Reporting database in the directory. For example:

    $ adr_launcher create --db_directory /tmp/nexus_db

    will create a new ADR database in /tmp/nexus_db.

  • save_config - save the nexus.conf file, applying any additional command line option changes

    This operation is used to change configuration settings. After reading the nexus.conf file, the options specified on the command line will be used to override options that were read and the result is then written into the nexus.conf file. For example:

    $ adr_launcher save_config --db_directory /tmp/nexus_db --instance_count 3

    will change the instance count setting to 3 and update the nexus.conf file.

  • migrate - update the database to the most recent version of Ansys Dynamic Reporting

    When run, the database is updated to the latest version. This operation can take some time, particularly if 3D scenes are included in the database as they may need to be reprocessed. Note, this command is not generally needed as the operation is performed automatically with the start command.

  • status - provide status output on the server

    This operation checks to see what the status of any ADR server associated with this database might be. For example, if no running server is associated with this database, the output might be:

    $ adr_launcher status --db_directory /tmp/nexus_db
server_status: stopped

    or if a server is running:

    $ adr_launcher status --db_directory /tmp/nexus_db
server_status: running
server_port: 8000
server_pid: 43984

  • start - start an ADR server.

    This operation will start a new ADR server for the database using the contents of the nexus.conf file along with any additional command line arguments. For example:

    $ adr_launcher start --db_directory /tmp/nexus_db --tray 1

    Will start a new server and install a control GUI in the system tray to allow the server to be monitored, launch the template editor, stop the server, etc.

    Note

    This command does not return until the server stops running. The server may be stopped using the adr_launcher 'stop' command run in another shell or via the desktop system tray menu.

  • stop - shut down a running ADR server.

    This operation will stop any server associated with the Ansys Dynamic Reporting database.

  • gui - run the ADR launcher GUI.

    The launcher GUI can be used to interactively modify the various database options. This operation is the default, so if no other operation is specified, the GUI will be launched.

ADR Server Architecture#

In order to be able to discuss ADR server options, it is important to understand how an ADR server works. In this section we describe the various processes and components of the ADR server once launched.

Image

The external URL interface is supplied by an instance of the nginx web server (nginx is included in the Ansys Dynamic Reporting distribution). The nginx server is used to serve up media files for ADR and serves as a load balancing interface for the actual ADR server instances. There can be one more more actual ADR server instances processing the various Ansys Dynamic Reporting web requests. For example, with two instances, two reports may be generated at the same time. Each of these servers talk to the nginx server over their own ports. All Ansys Dynamic Reporting metadata is stored in an SQL database. Currently SQLite and PostgreSQL(12 and above) are supported and the ADR servers will communication with those databases. Finally, Ansys Dynamic Reporting stores bulk data (e.g. images, movies, etc) in the local filesystem. The ADR servers and nginx will both need to be able to access this filesystem (nginx needs only read-only access). Finally, there is one additional process that serves to monitor the health of the ADR server. This service provides the mechanisms needed to shutdown the server, handle system tray operations, logging and other status functions.

Various server options control how ports are assigned to nginx and the ADR servers as well as the number of servers and the database specifics.

Server Options#

  • --instance_count ("Number of parallel servers to launch" in the GUI) specifies the number of ADR server instances that should be run.

  • --server_port ("Port" in the GUI) specifies the port number that the nginx instance should listen on for incoming requests. If the port number is set to 0, a random, open port will be used. This port number can be queried using the command line status option (it will also be include in the URL reported by the GUI). If setting this to a non-zero value, care must be taken to ensure that the port does not conflict with other processes.

  • --server_hostname ("Hostname" in the GUI) specifies the external hostname that the server will respond as. For example, if the server is configured to be accessed externally via the URL: http://my.nexusserver.com:80, the server hostname should be set to my.nexusserver.com. The nginx server will only accept incoming requests that resolve to this hostname. A common mistake is setting the hostname to 'localhost' or '127.0.0.1' and enabling remote access (the GUI will present a warning in this situation). Some features of the server will not work in such a setup, unless it has been hosted behind an appropriately configured proxy server. A rule of thumb is that the server hostname should be set to the name of the system as seen by other machines on the same network.

  • --internal_base_port ("Base port for dynamic allocation" in the GUI) specifies the port number where Ansys Dynamic Reporting will begin looking for unused ports when allocating ports for the ADR servers and other components. In the above example, the server_port was set to 0, so Ansys Dynamic Reporting started allocating ports for nginx and two ADR servers. Since all of the ports starting at 8000 were available, it selected 8000, 8001 and 8002 for the components.

  • --ssl_certificate (not available in the GUI) specifies the name of the ssl certificate file that nginx should use to serve up this connection. It will switch the ADR server to use https instead of http. --ssl_key must also be specified.

  • --ssl_key (not available in the GUI) specifies the name of the ssl key file that nginx should use to serve up this connection. It will switch the ADR server to use https instead of http. --ssl_certificate must also be specified.

  • --remote_session ADR has the ability to embed applications that are capable of rendering (remotely) via the vnc protocol into reports. There are built-in interfaces for local EnSight and EnVision sessions as well as custom sessions defined in the external_services.json file. For embedded remote sessions to work, this option must be enabled. The built-in EnSight and EnVision local sessions can be enabled by setting --local_sessions_ensight and --local_session_envision options.

  • --local_sessions_ensight This option selects the maximum number of local instances of the EnSight application that can be running in embedded form simultaneously. These sessions are available for .ens file data items. --remote_session must be enabled in addition to setting this to a non-zero value.

  • --local_sessions_envision This option selects the maximum number of local instances of the EnVision application that can be running in embedded form simultaneously. These sessions are available for .evsn file data items. --remote_session must be enabled in addition to setting this to a non-zero value.

  • --server_name ("Name" in the GUI) specifies a string that should appear in the server "About" page or the system tray menu to describe this server.

  • --postgresql_url ("Use postgresql", "Postgresql server hostname", "Postgresql server port", "Postgresql database name", "Username" and "Password" in the GUI) specifies that this ADR server should use a PostgreSQL server as the database instead of an SQLite database. From the command line, all of these options are passed as a single string in the form: "postgresql://user:password@host:port/database". In the GUI, the individual fields have been broken out for easier editing. There are also buttons in the GUI to test the database connection and initialize the PostgreSQL database that will store the Neuxs database tables. Note, all Ansys Dynamic Reporting databases begin as SQLite databases. Once created, they can be converted over to PostgreSQL.

  • --acls ("Enable per-item ACL support" in the GUI) specifies that per-data item access control should be enabled for this server. See the ACLs section for details.

  • --allow_remote_access Generally, ADR servers are only accessible from the same system the server is running on (e.g. a local desktop session). This option allows the server to be accessed from machines other than the one the ADR server is running on.

  • --allow_iframe_embedding By default, Ansys Dynamic Reporting prevents the HTML it generates to be displayed in <iframe>s for security. This option can be used to allow views of generated reports only from inside of an embedded <iframe>. Note, even after enabling this option, the content is still subjected to other <iframe> limits. For example, if one uses an SSL enabled server to serve up an <iframe> that contains an Ansys Dynamic Reporting report and that report is not accessed via 'localhost' or an SSL enabled Ansys Dynamic Reporting session, the content will still be blocked as one is not allowed to transition from SSL to non-SSL via the <iframe>. One last note, the admin functions (including login) are not supported in <iframe>s because of cookie limitations.

  • --max_upload_size There is a limit on the size of a file/data item that can be uploaded to an ADR server. By default, that limit is 5000 megabytes. This option allows that number to be adjusted from 1 to 20000 megabytes for a single data item.

  • --tray (not available in the GUI, but will be automatically enabled if launching a server from the GUI). This option is not saved in the nexus.conf file and is only used if --start is the action. If enabled, the launcher application will attempt to create a system tray menu for controlling the server being started. Note that the host running the launcher instance must be capable of displaying GUIs for this option to work.

  • --verbose ("Verbose logging" in the GUI). If enabled, additional diagnostic information will be logged when the server is run and the specifics of the configuration will be displayed on standard output. The logging information can be viewed from log files created in the Ansys Dynamic Reporting database directory or in the system tray logging dialog.

  • --debug (not available in the GUI). If enabled, the server will provide additional debugging information. This option should only be used when directed to by Ansys support.

  • --stdout (not available in the GUI). If enabled, the server will log all output to stdout. This can be useful for debugging.