Crossbill stack's dependencies installation

Crossbill stack products are 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.

Scenario 1: Automated installation (recommended)

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 below.

Scenario 2: Manual installation

The manual installation is designed to give you more control on component installation. The result of the following instructions doesn't differ from the automated installation. It is up to you to choose manual or automated dependency installation.

1. Install a database engine

The system works on PostgreSQL database engine version 12 or later. You can install a PostgreSQL engine on the same server as stack, or have a separate PostgreSQL database server, or use a third party hosted PostgreSQL database engine (for example, delivered by a cloud hosting). Here are the instructions for the same server installation:

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

Start a root session:

sudo su
#su -

Install PostgreSQL:

apt-get -y install postgresql

Create a directory for PostgreSQL data and configuration (optional):

mkdir /var/database
chown -R postgres:postgres /var/database

Initialise a database in a new directory:

PG_VER=$(su postgres -c 'psql -c "SHOW data_directory;" | grep -Po "/\K([0-9]+)"')
#echo $PG_VER

su postgres -c '/usr/lib/postgresql/'$PG_VER'/bin/initdb -D /var/database'

Configure a PostgreSQL daemon to start from the directory:

{ echo "[Service]"; 
  echo "Environment=PGDATA=/var/database";
} >/var/work/postgresql-override.conf
env SYSTEMD_EDITOR="cp /var/work/postgresql-override.conf" systemctl edit postgresql.service

Change the location of the database configuration files:

#vim /etc/postgresql/$PG_VER/main/postgresql.conf
sed -i "s@data_directory =[^#]*@data_directory = '/var/database' @" /etc/postgresql/$PG_VER/main/postgresql.conf
sed -i "s@hba_file =[^#]*@hba_file = '/var/database/pg_hba.conf' @" /etc/postgresql/$PG_VER/main/postgresql.conf
sed -i "s@ident_file =[^#]*@ident_file = '/var/database/pg_ident.conf' @" /etc/postgresql/$PG_VER/main/postgresql.conf
systemctl daemon-reload

systemctl enable postgresql
systemctl restart postgresql

Configure a firewall if required and if you open up an access to a database port from the Internet (optional):

firewall-cmd --zone=public --add-port=5432/tcp --permanent
firewall-cmd --reload

Set the administrator's password (replace the string DB_ADMIN_PASSWORD with a valid value):

su postgres -c "psql -c \"ALTER USER postgres PASSWORD 'DB_ADMIN_PASSWORD';\""

Configure PostgreSQL's pg_hba.conf file to always ask for a password:

sed -i -E 's@(host\s+all\s+all\s+127\.0\.0\.1/32\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(host\s+all\s+all\s+::1/128\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(host\s+replication\s+all\s+127\.0\.0\.1/32\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(host\s+replication\s+all\s+::1/128\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(local\s+all\s+all\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(local\s+replication\s+all\s+)trust@\1md5@' /var/database/pg_hba.conf
#host all 0.0.0.0/0 md5
#vim /etc/postgresql/$PG_VER/main/postgresql.conf
#listen_addresses = '*'

systemctl restart postgresql

Exit the root session:

exit

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

Start a root session:

sudo su
#su -

Configure a PostgreSQL repository:

echo "exclude=postgresql*" >> /etc/yum/pluginconf.d/rhnplugin.conf
yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm

Install PostgreSQL:

yum -y install postgresql

Create a directory for PostgreSQL data and configuration (optional):

mkdir /var/database
chown -R postgres:postgres /var/database

Initialise a database in a new directory:

PG_VER=$(su postgres -c 'psql -c "SHOW data_directory;" | grep -Po "/\K([0-9]+)"')
#echo $PG_VER

su postgres -c '/usr/lib/postgresql/'$PG_VER'/bin/initdb -D /var/database'

Configure a PostgreSQL daemon to start from the directory:

{ echo "[Service]"; 
  echo "Environment=PGDATA=/var/database";
} >/var/work/postgresql-override.conf
env SYSTEMD_EDITOR="cp /var/work/postgresql-override.conf" systemctl edit postgresql.service

Change the location of the database configuration files:

#vim /etc/postgresql/$PG_VER/main/postgresql.conf
sed -i "s@data_directory =[^#]*@data_directory = '/var/database' @" /etc/postgresql/$PG_VER/main/postgresql.conf
sed -i "s@hba_file =[^#]*@hba_file = '/var/database/pg_hba.conf' @" /etc/postgresql/$PG_VER/main/postgresql.conf
sed -i "s@ident_file =[^#]*@ident_file = '/var/database/pg_ident.conf' @" /etc/postgresql/$PG_VER/main/postgresql.conf
systemctl daemon-reload

systemctl enable postgresql
systemctl restart postgresql

Configure a firewall if required and if you open up an access to a database port from the Internet (optional):

firewall-cmd --zone=public --add-port=5432/tcp --permanent
firewall-cmd --reload

#vim /etc/sysconfig/selinux
#sestatus

Set the administrator's password (replace the string DB_ADMIN_PASSWORD with a valid value):

su postgres -c "psql -c \"ALTER USER postgres PASSWORD 'DB_ADMIN_PASSWORD';\""

Configure PostgreSQL's pg_hba.conf file to always ask for a password:

sed -i -E 's@(host\s+all\s+all\s+127\.0\.0\.1/32\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(host\s+all\s+all\s+::1/128\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(host\s+replication\s+all\s+127\.0\.0\.1/32\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(host\s+replication\s+all\s+::1/128\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(local\s+all\s+all\s+)trust@\1md5@' /var/database/pg_hba.conf
sed -i -E 's@(local\s+replication\s+all\s+)trust@\1md5@' /var/database/pg_hba.conf
#host all 0.0.0.0/0 md5
#vim /etc/postgresql/$PG_VER/main/postgresql.conf
#listen_addresses = '*'

systemctl restart postgresql

Exit the root session:

exit

Download PostgreSQL's .exe from an official website and install it following the prompts.

During installation, set the administrator's password (for user postgres).

Make sure the database is prompting for password on connection. Check the file c:\Program Files\PostgreSQL\15\data\pg_hba.conf for security settings. For example:

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     scram-sha-256
# IPv4 local connections:
host    all             all             127.0.0.1/32            scram-sha-256
# IPv6 local connections:
host    all             all             ::1/128                 scram-sha-256
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     scram-sha-256
host    replication     all             127.0.0.1/32            scram-sha-256
host    replication     all             ::1/128                 scram-sha-256

Create a firewall rule for port 5432 if required and if you open up an access to a database port from the Internet (optional).

Make sure the database engine is available for all stack components. Configure a network firewall rule for a database port if required.

2. Install a web server

Crossbill stack includes the web applications hosted by a web server. The web server is serving user requests and directs it to .NET applications or transmits the static files.

On Windows, it is recommended to use the IIS web server. On Linux, it is recommended to use the Nginx web server.

The Apache web server is not recommended. Although Apache can be configured manually, it is not supported by Crossbill Central, so no way you can automatically deploy Apache-based websites from Central at the moment.

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

Start a root session:

sudo su
#su -

Install the Nginx web server:

apt-get -y install nginx

Enable Nginx to start as a service:

systemctl enable nginx
systemctl stop nginx
systemctl start nginx

Prepare the configuration directories:

mkdir /etc/nginx/sites-available
rm -rf /etc/nginx/sites-enabled
ln -s /etc/nginx/sites-available /etc/nginx/sites-enabled

Add a user for a web server process. On Debian, execute

adduser www-data

On Ubuntu, execute

adduser www-data www-data

Create a directory for Nginx logs:

mkdir /var/nginx
mkdir /var/nginx/log
chown -R www-data:www-data /var/nginx

Configure the DNS names locally to ensure there are no delays on local connections:

vim /etc/hosts

The sample configuration may look like this:

127.0.0.1       localhost my-dns-name.com central.my-dns-name.com
127.0.1.1       debian

# The following lines are desirable for IPv6 capable hosts
::1     localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

Configure a firewall if required (optional):

firewall-cmd --zone=public --add-port=80/tcp --permanent
firewall-cmd --reload

Exit the root session:

exit

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

Start a root session:

sudo su
#su -

Install the Nginx web server:

yum -y install nginx

Enable Nginx to start as a service:

systemctl enable nginx
systemctl stop nginx
systemctl start nginx

Prepare the configuration directories:

mkdir /etc/nginx/sites-available
rm -rf /etc/nginx/sites-enabled
ln -s /etc/nginx/sites-available /etc/nginx/sites-enabled

Add a user for a web server process:

useradd www-data

Create a directory for Nginx logs:

mkdir /var/nginx
mkdir /var/nginx/log
chown -R www-data:www-data /var/nginx

Configure the DNS names locally to ensure there are no delays on local connections:

vim /etc/hosts

The sample configuration may look like this:

127.0.0.1       localhost my-dns-name.com central.my-dns-name.com
127.0.1.1       debian

# The following lines are desirable for IPv6 capable hosts
::1     localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters

Configure a firewall if required (optional):

firewall-cmd --zone=public --add-port=80/tcp --permanent
firewall-cmd --reload

#vim /etc/sysconfig/selinux
#sestatus

Exit the root session:

exit

On Windows Server, you have to enable the IIS server role.

From a start screen, select Server Manager Manage Add Roles and Features and follow the prompts. On non-server Windows, use Start Control Panel Programs Turn Windows features on or off. When required select the following roles if not selected yet:

  • Web server (IIS) / Web Server / Common HTTP Features / Default Document
  • Web server (IIS) / Web Server / Common HTTP Features / Directory Browsing
  • Web server (IIS) / Web Server / Common HTTP Features / HTTP Errors
  • Web server (IIS) / Web Server / Common HTTP Features / Static Content
  • Web server (IIS) / Web Server / Common HTTP Features / HTTP Redirection
  • Web server (IIS) / Web Server / Health and Diagnostics / HTTP Logging
  • Web server (IIS) / Web Server / Performance / Static Content Compression
  • Web server (IIS) / Web Server / Security / Request Filtering
  • Web server (IIS) / Web Server / Security / Basic Authentication
  • Web server (IIS) / Web Server / Security / Windows Authentication
  • Web server (IIS) / Management Tools / IIS Management Console
  • Web server (IIS) / Management Tools / IIS Management Scripts and Tools
  • Web server (IIS) / Management Tools / Management Service

3. Install the .NET SDK

Crossbill stack requires the .NET 8 SDK or later to be installed. Follow the installation instructions given or instructions from a .NET official website.

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

Start a root session:

sudo su
#su -

On Debian, configure the .NET repository. Make sure to use your Debian version if not 12:

wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
apt-get update

Install the .NET 8 SDK:

apt-get install -y dotnet-sdk-8.0

Check the runtime version:

dotnet --info

Exit the root session:

exit

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

Start a root session:

sudo su
#su -

On CentOS, configure the .NET repository. Make sure to use your CentOS version if not 7:

rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm

On CentOS, install the .NET 8 SDK:

yum install dotnet-sdk-8.0

On RHEL or Oracle Linux, install the .NET 8 SDK:

dnf install dotnet-sdk-8.0

Check the runtime version:

dotnet --info

Exit the root session:

exit

On Windows Server download and install the following .NET 8 packages:

  • .NET 8 SDK x64 for Windows
  • ASP.NET Core Runtime 8 Hosting Bundle

Once installed open a command line (Start type cmd) and check the .NET version:

dotnet --info

4. Install the additional packages

Third party libraries are required for the products to work. The libraries can be installed using a command line or bash interface. 

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

Start a root session:

sudo su
#su -

Install EF Core as a global utility:

dotnet tool install --global dotnet-ef --version 8.0.0

Install the additional packages:

apt-get -y install libgdiplus

apt-get -y install unzip vim
apt-get -y install realmd
apt-get -y install syslog-ng
apt-get -y install gssntlmssp

Exit the root session:

exit

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

Start a root session:

sudo su
#su -

Install EF Core as a global utility:

dotnet tool install --global dotnet-ef --version 8.0.0

Install the additional repo:

yum -y install epel-release
yum -y update

Install the additional packages:

yum -y install libunwind openssl libnghttp2 libidn krb5-libs libuuid lttng-ust zlib libicu

yum -y install unzip vim
yum -y install realmd
yum -y install syslog-ng
yum -y install gssntlmssp

Exit the root session:

exit

Open a command line (Start type cmd) and install EF Core as a global utility:

dotnet tool install --global dotnet-ef --version 8.0.0

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