Nexus Server Launcher

Parent Previous Next

Nexus Launcher Command Line

The Nexus 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 Nexus server instance.  The command line greatly simplifies the creation and maintenance of Nexus instances located on remote server with no native GUI interfaces (e.g. AWS or Azure servers).


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:>nexus_launcher.bat -h

usage: [-h] [--db_directory database_directory]

                            [--instance_count number_of_server_instances]

                            [--server_port server_port]

                            [--server_hostname server_hostname]

                            [--internal_base_port base_port]

                            [--ssl_certificate certificate_file]

                            [--ssl_key key_file] [--server_name "Name"]

                            [--postgresql_url PostgreSQL_URL]

                            [--acls yes|no|true|false|1|0]

                            [--tray yes|no|true|false|1|0]

                            [--verbose yes|no|true|false|1|0]

                            [--debug yes|no|true|false|1|0]


Version 2021 R2: Configure/launch a Nexus server

positional arguments:

  operation             'start' : Start the server selected by the specified database directory.

                        'stop' : Shut down any server associated with the specified database directory.

                        'status' : Display the status of any server associated with the specified database directory.

                        'create' : Create a new Nexus database in the database directory.

                        'migrate' : Update the database schema to the latest.

                        'save_config' : Save the server configuration as the default for this database. Do not launch a server.

                        'gui' : start the launcher configuration editor GUI (default operation).

optional arguments:

  -h, --help            show this help message and exit

  --db_directory database_directory

                        Directory containing the Nexus database

  --instance_count number_of_server_instances

                        Number of Nexus server instances to launch

  --server_port server_port

                        Port number to run the server on.  0=select dynamically

  --server_hostname server_hostname

                        Hostname to run the server on (external hostname)

  --internal_base_port base_port

                        Port number base to allocate server instances, etc.  0=select dynamically

  --ssl_certificate certificate_file

                        Name of the SSL certificate file to encrypt the session with

  --ssl_key key_file    Name of the SSL key file to encrypt the session with

  --server_name "Name"  The human readable name to use for the database

  --postgresql_url PostgreSQL_URL

                        URL to the PostgreSQL database to use: "postgresql://user:password@host:port/database"

  --acls yes|no|true|false|1|0

                        Enable/disable per-item ACL functionality (default: false).

  --tray yes|no|true|false|1|0

                        Enable desktop tray integration (default: false).

  --verbose yes|no|true|false|1|0

                        Enable verbose output (default: false).

  --debug yes|no|true|false|1|0

                        Run the server in debug mode (default: false).


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 Nexus 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:

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 Nexus database in the directory. For example:  

$ nexus_launcher create --db_directory /tmp/nexus_db 

will create a new nexus databased in /tmp/nexus_db.

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:  

$ nexus_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.

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.  

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

$ nexus_launcher status --db_directory /tmp/nexus_db

server_status:  stopped

or if a server is running:

$ nexus_launcher status --db_directory /tmp/nexus_db

server_status:  running

server_port:    8000

server_pid:     43984

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

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

Will start a new server (and not return until the server is stopped) and will include a control GUI in the system tray to allow the server to be monitored, launch the template editor, stop the server, etc.

This operation will stop any server associated with the Nexus database.

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.

Nexus Server Architecture

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

The external URL interface is supplied by an instance of the nginx web server (nginx is included in the Nexus distribution). The nginx server is used to serve up media files for Nexus and serves as a load balancing interface for the actual Nexus server instances.  There can be one more more actual Nexus server instances processing the various Nexus 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 Nexus metadata is stored in an SQL database. Currently SQLite and PostgreSQL are supported and the Nexus servers will communication with those databases. Finally, Nexus stores bulk data (e.g. images, movies, etc) in the local filesystem.  The Nexus 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 Nexus 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 Nexus servers as well as the number of servers and the database specifics.

Server Options