1. Documentation
  2. Crossbill stack docs
  3. 24.x
  4. On-premises installation

Crossbill stack on-premises installation

Crossbill stack is dependent on third-party components. So, make sure to prepare the server environment and install the dependencies before continuing to the following installation instructions:

Prepare the installer's parameters

All Crossbill installers use the Crossbill Install utility to install the product components. In some scenarios, the utility is run directly from a command line. In some scenarios, it is run indirectly from a user interface (on Windows). Anyway, the utility uses preconfigured parameters to install the components. In this section we provide a brief description of the parameters and instructions on each parameter's value.

The Crossbill Install utility uses a deployment configuration file config.jsconf. The file uses JSON format. The file's parameters under the replacements section should be filled before the Crossbill Install utility run according to the following information.

Windows interface parameter Parameter from config.jsconf Pattern Expected value and instructions
DNS Name (Host Header) @{DNS} my-domain.com The DNS name for Crossbill Cone Web application. This is the public domain name prepared during the DNS configuration step.
Environment @{Environment} PROD The name of an environment. For example DEV, UAT, etc. Can be used to deploy multiple product instances to the same server. Use PROD for any common configuration.
Public Website port @{BaseSitePort} 80 The port for a website. This is the port used to serve user requests. Use 80 for any common configuration.
Database Host @{DatabaseHost} 127.0.0.1 The host name of a database server. Use 127.0.0.1 for the local database.
Database Name @{DatabaseName} crossbill The name of a database to be created for the product operation.
Database Admin User @{DatabaseAdminUser} postgres The name of the database administrator's account.
Database Admin Password @{DatabaseAdminPassword} Secret string The password set for the database administrator's account on database installation step.
Database User @{DatabaseUser} crossbill The name of the database account for the product connection. This account will be created by the installer.
Database Password @{DatabasePassword} Secret string The password of the database account for the product connection. This password will be assigned to the account by the installer. Provide at least 20 chars including digits, mixed case letters and symbols.
Database Connection String @{DatabaseConnection} The connection string for the database. Use default value for any common configuration.
Random Secret (insert any 40 chars or use existing for updates) @{RandomSecret} Secret string The secret password for sensitive data encryption. Insert 40 chars including digits and mixed case letters.
Random Secret IV (insert any 20 chars or use existing for updates) @{RandomSecretIV} Secret string The secret password for sensitive data encryption. Insert 20 chars including digits and mixed case letters.
Logs Directory @{LogsDirectory} Location The directory where to place log files. Use default value for any common configuration.
Services Installation Directory for Environment @{ServiceInstallationDirectory} Location The directory where to place the service (daemon) files. Use default value for any common configuration.
Websites Installation Directory for Environment @{WebInstallationDirectory} Location The directory where to place the web application files. Use default value for any common configuration.
Port for Central Agent service @{CentralAgentPort} 5002 The port number to use for Central Agent service. Use default value for any common configuration.
URL for Central service @{CentralAgentURL} The URL allocated for Central Agent service. Use default value for any common configuration.
Theme @{Theme} Theme The theme name for application styling. Use default value for any common configuration.

Install Crossbill stack

The deployment scenarios can vary depending on requirements. On Windows, it is recommended to use .exe installer package, while on Linux, .deb or .rpm package. Crossbill also provides a .zip archive which contains a universal installer and can be used for any operating system (including x86 Windows).

The installer package can be a standalone package or a web package. The standalone package already contains all the required components packed and bundled. The web package contains the Crossbill Install utility and a configuration file only, so it requires a network connection to download the selected components during installation.

For installation, follow one of the scenarios below.

Scenario 1: Install using the installer file

To install the Crossbill stack components follow the instructions for a target operating system:

  1. Open a terminal or connect via SSH to execute the commands.

  2. Start a root session:

    sudo su
  3. Open a Crossbill stack downloads page in a web browser and copy the .deb file URL for the latest application version. Put the .deb file URL in the following command and execure it: 
    mkdir /var/work
cd /var/work
curl -o installer.deb -L https://storage.googleapis.com/crossbillsoft/24.11.0/Crossbill.Stack.x64.24.11.0.deb
  4. Install .deb package: 
    apt-get -y install ./installer.deb

  5. The package installs the Crossbill Install utility to /usr/share/Crossbill.Install. The directory contains a deployment configuration file config.jsconf.

    Edit the deployment configuration config.jsconf file and fill in the parameters according to the recommendations given before:

    vim /usr/share/Crossbill.Install/config.jsconf

  6. Once the parameters are filled and saved to the file, run the Crossbill Install utility:

    cd /usr/share/Crossbill.Install/
dotnet Crossbill.Install.dll
  7. Restart the applications for the target environment (PROD by default): 
    service Crossbill.Central.Agent-CROSS restart
service Crossbill.Central.Web-CROSS restart
service Crossbill.Cone.Web-PROD restart
service Crossbill.Bone.Web-PROD restart
service Crossbill.Signalman-PROD restart
  8. Make sure to save the config.jsconf file in a safe place and remove it from /usr/share/Crossbill.Install/ directory.

  9. Exit the root session:

    exit
  10. The installation is completed. Now continue to initial configuration of the system.
  1. Open a terminal or connect via SSH to execute the commands.

  2. Start a root session:

    sudo su
  3. Open a Crossbill stack downloads page in a web browser and copy the .rpm file URL for the latest application version. Put the .rpm file URL in the following command and execure it: 
    mkdir /var/work
cd /var/work
curl -o installer.rpm -L https://storage.googleapis.com/crossbillsoft/24.11.0/Crossbill.Stack.x64.24.11.0.rpm
  4. Install .rpm package: 
    yum localinstall ./installer.rpm

  5. The package installs the Crossbill Install utility to /usr/share/Crossbill.Install. The directory contains a deployment configuration file config.jsconf.

    Edit the deployment configuration config.jsconf file and fill in the parameters according to the recommendations given before:

    vim /usr/share/Crossbill.Install/config.jsconf
  6. Once the parameters are filled and saved to the file, run the Crossbill Install utility: 
    cd /usr/share/Crossbill.Install/
dotnet Crossbill.Install.dll
  7. Restart the applications for the target environment (PROD by default): 
    service Crossbill.Central.Agent-CROSS restart
service Crossbill.Central.Web-CROSS restart
service Crossbill.Cone.Web-PROD restart
service Crossbill.Bone.Web-PROD restart
service Crossbill.Signalman-PROD restart
  8. Make sure to save the config.jsconf file in a safe place and remove it from /usr/share/Crossbill.Install/ directory.

  9. Exit the root session:

    exit
  10. The installation is completed. Now continue to initial configuration of the system.
  1. Open a Crossbill stack downloads page in a web browser. Download the latest application version to a target server.
  2. Run the installer as administrator and follow the prompts.
  3. On features screen, fill in the parameters according to the recommendations given before and click Install.
  4. Open services snap-in (Start type Services). Restart the Crossbill Signalman service for the target environment (PROD by default).
  5. The installer saves the settings in a config.jsconf file for future use. Make sure to save the config.jsconf file in a safe place and remove it from the installer's directory.
  6. The installation is completed. Now continue to initial configuration of the system.

Scenario 2: Install using the .zip archive for any OS

Crossbill provides a .zip archive which contains a Crossbill Install utility and can be used for any operating system (including x86 Windows). To install the Crossbill stack components, follow the instructions for a target operating system:

  1. Open a terminal or connect via SSH to execute the commands.

  2. Start a root session:

    sudo su
  3. Open a Crossbill stack downloads page in a web browser and copy the .zip file URL for the latest application version. Put the .zip file URL in the following command and execure it: 
    mkdir /var/work
cd /var/work
curl -o installer.zip -L https://storage.googleapis.com/crossbillsoft/24.11.0/Crossbill.Stack.x64.24.11.0.zip
  4. Unpack the .zip archive: 
    unzip installer.zip
rm installer.zip

  5. The extracted files are the files of Crossbill Install utility and a deployment configuration file config.jsconf.

    Edit the deployment configuration config.jsconf file and fill in the parameters according to the recommendations given before:

    vim config.jsconf

  6. Once the parameters are filled and saved to the file, run the Crossbill Install utility:

    dotnet Crossbill.Install.dll
  7. Restart the applications for the target environment (PROD by default): 
    service Crossbill.Central.Agent-CROSS restart
service Crossbill.Central.Web-CROSS restart
service Crossbill.Cone.Web-PROD restart
service Crossbill.Bone.Web-PROD restart
service Crossbill.Signalman-PROD restart
  8. Make sure to save the config.jsconf file in a safe place and remove it from /var/work/ directory.

  9. Exit the root session:

    exit
  10. The installation is completed. Now continue to initial configuration of the system.
  1. Open a terminal or connect via SSH to execute the commands.

  2. Start a root session:

    sudo su
  3. Open a Crossbill stack downloads page in a web browser and copy the .zip file URL for the latest application version. Put the .zip file URL in the following command and execure it: 
    mkdir /var/work
cd /var/work
curl -o installer.zip -L https://storage.googleapis.com/crossbillsoft/24.11.0/Crossbill.Stack.x64.24.11.0.zip
  4. Unpack the .zip archive: 
    unzip installer.zip
rm installer.zip

  5. The extracted files are the files of Crossbill Install utility and a deployment configuration file config.jsconf.

    Edit the deployment configuration config.jsconf file and fill in the parameters according to the recommendations given before:

    vim config.jsconf

  6. Once the parameters are filled and saved to the file, run the Crossbill Install utility:

    dotnet Crossbill.Install.dll
  7. Restart the applications for the target environment (PROD by default): 
    service Crossbill.Central.Agent-CROSS restart
service Crossbill.Central.Web-CROSS restart
service Crossbill.Cone.Web-PROD restart
service Crossbill.Bone.Web-PROD restart
service Crossbill.Signalman-PROD restart
  8. Make sure to save the config.jsconf file in a safe place and remove it from /var/work/ directory.

  9. Exit the root session:

    exit
  10. The installation is completed. Now continue to initial configuration of the system.
  1. Open a Crossbill stack downloads page in a web browser. Download .zip file for the latest application version to a target server.
  2. Unzip the .zip archive to a local directory.

  3. The extracted files are the files of Crossbill Install utility and a deployment configuration file config.jsconf.

    Edit the deployment configuration config.jsconf file with a text editor and fill in the parameters according to the recommendations given before.

  4. Run Crossbill.Install.exe as administrator (either from a directory or from a command line).
  5. Open services snap-in (Start type Services). Restart the Crossbill Signalman service for the target environment (PROD by default).
  6. Make sure to save the config.jsconf file in a safe place and remove it from a local directory.
  7. The installation is completed. Now continue to initial configuration of the system.

Scenario 3: Install using Crossbill Central

If you have Crossbill Central already installed, you can install Crossbill stack from Crossbill Central web interface. Follow the steps:

  1. Open a web browser and navigate to Crossbill Central.
  2. Log into the system with administrative login and password.
  3. Under the Applications tab, select the required component on a right side and click Install.
  4. Fill the installer parameters in a popup window. Click Deploy.
  5. The installed application will appear in the left panel.
  6. To install a plugin or theme, click the application's title and repeat steps 3-5.
  7. The installation is completed. Now continue to initial configuration of the system.

The applications and plugins included in Crossbill stack:

Component Component ID Component type Mandatory / Optional
Crossbill Cone Web Crossbill.Cone.Web Application Mandatory
Crossbill Cone Default Theme Crossbill.Theme Plugin for Crossbill.Cone.Web Mandatory
Crossbill Cone API Crossbill.Cone.API Application Optional
Versioning Plugin for Crossbill Cone Crossbill.Plugins.DataVersioning.Git Plugin for Crossbill.Cone.Web Optional
PDF Plugin for Crossbill Cone Crossbill.Plugins.PDF.JsReport Plugin for Crossbill.Cone.Web Optional
Crossbill Bone Web Crossbill.Bone.Web Application Mandatory
Crossbill Bone Default Theme Crossbill.Theme Plugin for Crossbill.Bone.Web Mandatory
Crossbill Bone API Crossbill.Bone.API Application Optional
Versioning Plugin for Crossbill Bone Crossbill.Plugins.DataVersioning.Git Plugin for Crossbill.Bone.Web Optional
PDF Plugin for Crossbill Bone Crossbill.Plugins.PDF.JsReport Plugin for Crossbill.Bone.Web Optional
Crossbill Signalman Crossbill.Signalman Application Mandatory
Operations Plugin for Signalman Crossbill.Signalman.Plugins.Operations Plugin for Crossbill Signalman Mandatory
Users Plugin for Signalman Crossbill.Signalman.Plugins.Users Plugin for Crossbill Signalman Mandatory
Cone Plugin for Signalman Crossbill.Signalman.Plugins.Cone Plugin for Crossbill Signalman Mandatory
Bone Plugin for Signalman Crossbill.Signalman.Plugins.Bone Plugin for Crossbill Signalman Mandatory

Troubleshooting

The Crossbill Install utility logs all operations for troubleshooting. The log is located in a common logs location or in the installer's current directory (on Windows). Here are the common logs locations:

Open a terminal or connect via SSH to execute the commands.

Start a root session:

sudo su
#su -

Show log for the Crossbill Install utility:

cat /var/Crossbill/CROSS/logs/Crossbill.Install/Crossbill.Install.log

Show log for the Crossbill Central Agent utility:

cat /var/Crossbill/CROSS/logs/Crossbill.Central.Agent/Crossbill.Central.Agent.log

Exit the root session:

exit

Open a terminal or connect via SSH to execute the commands.

Start a root session:

sudo su
#su -

Show log for the Crossbill Install utility:

cat /var/Crossbill/CROSS/logs/Crossbill.Install/Crossbill.Install.log

Show log for the Crossbill Central Agent utility:

cat /var/Crossbill/CROSS/logs/Crossbill.Central.Agent/Crossbill.Central.Agent.log

Exit the root session:

exit

Open the following files in a text editor to see the log:

C:\Crossbill\CROSS\logs\Crossbill.Install\Crossbill.Install.log
C:\Crossbill\CROSS\logs\Crossbill.Central.Agent\Crossbill.Central.Agent.log