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

Crossbill Nest on-premises installation

Server preparation

1. Infrastructure planning

Before Crossbill Nest on-premises installation, prepare a target server environment:

  1. Plan the number of physical servers or virtual machines:
    • The basic installation can be done using a single server or a single virtual machine.
    • The advanced installation may include multiple servers in a server farm. The current server roles available for farm installation are:
      • database server (or database cluster),
      • application server (for Crossbill Signalman application),
      • licensing server (for Crossbill Central Agent application),
      • web server (for Crossbill Nest application).
      For farm installation, use the same installation instructions while selecting only components for a specific server role or changing the Crossbill Install's config.jsconf file accordingly. Contact support if you need more information on the server farm deployment.
  2. Prepare a physical server or start a virtual machine which meet the system requirements
  3. For the physical server, install a Linux or Windows operating system.

2. Configure the DNS names (domain names)

To access the Crossbill Nest's web applications, it is recommended to use the DNS names (domain names). The domain name should point to your server's public IP address. There are some configuration options available:

  • For a public web portal deployment, consider purchasing a domain name from any ICANN authorised registrars or configure a subdomain for any name you already have.
  • For a local network deployment, consider configuring a local network's DNS records.
  • If you deploy the system locally on a computer for development purposes, consider configuring a local hosts file to any name you like. On Windows the file is located at C:\Windows\System32\drivers\etc\hosts On Linux the location is /etc/hosts

For Crossbill Nest, the following DNS configuration is recommended:

Crossbill Nest's component Suggested DNS name pattern DNS record type DNS record points to Optional / Mandatory
Crossbill Nest nest.my-domain.com A-record Public IP address of a web server Mandatory
Crossbill Central Web central.my-domain.com A-record Public IP address of a licensing server Mandatory

Note that there are no restrictions on domain names and domain name levels. So, it is up to you to use almost any domain name pattern.

3. Dependencies installation

Crossbill Nest is dependent on third-party software components which can be installed separately. The third-party components include a web server, a PostgreSQL database engine, a .NET SDK runtime and required libraries.

The component installation is automated by a script. We recommend to use it for any fresh clean server installation. Alternatively, for existing environments, or if you need more control on component installation you can follow the instructions for manual installation.

The automated dependency configuration script accepts two parameters: a directory name to place the component's files and a password for database administrator account. Default value /var can be used as a directory name. Any string can be used as a password.

Note: We recommend to generate a password using an online password generator. Make sure to save the password in a secure place.

Here are the instructions for the clean server installation using automated dependency configuration script:

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

Start a root session:

sudo su

Download the automated dependency configuration script:

curl -o dependencies.sh -L https://crossbillsoftware.com/dependencies.debian.sh

Execute the script. Make sure to replace DB_ADMIN_PASSWORD with the password you wish to use for the database admin user:

sh ./dependencies.sh /var DB_ADMIN_PASSWORD

Remove the script file:

rm ./dependencies.sh

Exit the root session:

exit

That's it. All dependencies should be installed now including Nginx, PostgreSQL and .NET SDK.

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

Start a root session:

sudo su

Download the automated dependency configuration script:

curl -o dependencies.sh -L https://crossbillsoftware.com/dependencies.rhel.sh

Execute the script. Make sure to replace DB_ADMIN_PASSWORD with the password you wish to use for the database admin user:

sh ./dependencies.sh /var DB_ADMIN_PASSWORD

Remove the script file:

rm ./dependencies.sh

Exit the root session:

exit

That's it. All dependencies should be installed now including Nginx, PostgreSQL and .NET SDK.

Follow the manual installation instructions for Windows.

If for some reason the automated script did not fit to your needs, follow the manual installation steps.

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} nest.my-domain.com The DNS name for Crossbill Nest 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 Nest

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 Nest 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 Nest 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.3/Crossbill.Nest.x64.24.11.3.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.Nest-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 Nest 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.3/Crossbill.Nest.x64.24.11.3.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.Nest-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 Nest 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 Nest 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 Nest 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.3/Crossbill.Nest.x64.24.11.3.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.Nest-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 Nest 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.3/Crossbill.Nest.x64.24.11.3.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.Nest-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 Nest 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 Nest 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 Nest:

Component Component ID Component type Mandatory / Optional
Crossbill Nest Crossbill.Nest Application Mandatory
Crossbill Nest Default Theme Crossbill.Theme Plugin for Crossbill.Nest Mandatory
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

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