AsterionDB Zero Trust Architecture

Sand Alone Installation Guide

Table of Contents

Introduction

The purpose of this guide is to show you how to install AsterionDB upon a single computer where all of the components are co-located. Our installation process is designed to be familiar to experienced Oracle database users and system administrators.

Please reach out to us if you need additional assistance.If you are just getting started, you may want to check out the first, which details how to install AsterionDB in Oracle Cloud Infrastructure using the Autonomous Database. It provides a bit more detail and context.

Objective

This guide will walk you through the process of installing AsterionDB upon a single computer. The documentation does not include instructions on creating a load balancer nor does it detail the process of properly exposing AsterionDB on the internet with an SSL certificate.

Prerequisites

These prerequisites will give you a good understanding of what you need to know in advance in order to install and use AsterionDB.

Most of the steps are pretty simple but we don’t want to turn anyone away for lack of understanding. So, please feel free to reach out to us for help on your initial installation.

AsterionDB has a very simple set of prerequisites, starting with an Oracle Database. Any version of the database (XE, Standard, Enterprise, etc.) can be used. You can also install AsterionDB on a single, turn-key machine which includes the database.

Our other primary dependency is OracleLinux v8.9. This is used for the compute instance that runs all of the AsterionDB framework components as well as a JavaScript web application served by Nginx.

You should also be familiar with common, simple power-user tasks such as:

  • Creating a compute instance from a Marketplace Image
  • Downloading a file to a known location
  • Accessing a file using a file browser or the command line
  • Changing file permissions and properties
  • SSH
  • Copying and pasting text
  • Installing software applications
  • Using Windows Powershell if necessary

Finally, you should have some appropriate evaluation content to upload into AsterionDB such as a few photographs and PDF documents. Nothing too big or extensive – just enough to get yourself going.

Provisioning

How you provision the computer will be guided by your specific requirements, primarily centered on how the database needs to be configured. The basic requirements for the AsterionDB framework (everything except the database) are not extensive. You will want at least one CPU and 8GB of RAM.

The Installation Process

The installation process will follow this outline:

  • Create a compute instance using the AsterionDB Marketplace Image
  • Remove Oracle’s Instant-Client software
  • Install and configure the Oracle Database
  • Install AsterionDB into the newly created Oracle Database

Create a Compute Node from the AsterionDB Marketplace Image

Using the AsterionDB Marketplace Image as your starting point ensures that you have all of the software necessary to run AsterionDB already installed. There are only a few steps to take in order to use this image as a standalone machine.

Remove Oracle’s Instant-Client Software

The AsterionDB Marketplace Image has Oracle’s instant-client software pre-installed. This will conflict with the Oracle Database package. Execute the following command to remove Oracle’s instant-client software:
				
					sudo dnf remove -y oracle-instantclient-sqlplus.x86_64 oracle-instantclient-basic.x86_64 oracle-instantclient-tools.x86_64
				
			

Install and Configure the Oracle Database

Install the database edition of your choice upon the compute node. Instructions for doing this are beyond the scope of this document.

Install AsterionDB Into the Database

At this point you will need to connect as the ‘asterion’ user:

 

				
					sudo bash
su -l asterion

				
			

The standard installation of AsterionDB is designed to utilize Oracle’s Instant-Client software. With a standalone installation, we will be switching over to using the network software that comes with the database.

You will need to remove some lines from the ‘.bash_profie’ script for the Asterion user. Edit /home/asterion/.bash_profile and remove these lines:
  • export ORACLE_HOME=”/usr/lib/oracle/21/client64/lib”
  • export LD_LIBRARY_PATH=”/usr/local/lib:/usr/lib/oracle/21/client64/lib”
  • export PATH=/sbin:/bin:/usr/sbin:/usr/bin:/root/.local/bin:/root/bin:/usr/lib/oracle/21/client64/bin
  • export TWO_TASK=%TNS_DB_ENTRY% # Found in TNSNAMES.ora file
  • #export TNS_ADMIN=%PATH_TO_WALLET% # Used if Wallet is not in the default location
Insert the following lines into the .bash_profile script file (note: this example assumes OracleXE):
				
					export ORACLE_SID=XE
export ORAENV_ASK=NO 
. /opt/oracle/product/21c/dbhomeXE/bin/oraenv
export TWO_TASK=XEPDB1

				
			

Next, you will need to pickup the new settings in .bash_profile. Do so with this command:

				
					source .bash_profile

				
			

Run the PDB Configuration Script

As mentioned earlier, you will need to configure the PDB prior to installing AsterionDB. This only needs to be done once. For this step you will need the SYSDBA username and password in order to access the CDB as a SYSDBA. Run this script:

				
					cd /home/asterion/asterion/oracle/admin
./configurePDB.sh
				
			

This script will connect to the database as a SYSDBA, display the available PDBs and ask you which PDB will be configured. Enter the name of the target PDB and press Enter:

Update The Installation Settings

We use a script to store your settings in order to efficiently drive the installation process.

Execute this script to create the installation settings file:

				
					./updateConfig.sh
				
			
This script will prompt you for the following values:
  • Specify the database type: AUTONOMOUS(default) or PDB
    • Most on premises installations will be against a PDB database
  • Enter in Database connection string or alias your_pdb(default)
    • You can press Enter to accept the default, which is taken from the TWO_TASK environment variable
  • Database Admin User SYSTEM(default)
    • You can press Enter to accept the default, or enter a value other than SYSTEM
  • Database Admin Password
  • Enter the External facing Hostname:Port localhost:8080(default)
    • Depending upon your environment, you may be specifying a fully qualified hostname, an IP address and possibly port 8080. This will depend upon how your compute node is accessed on the network.
  • Do you want enable SSL (y/n – default y)?
    • Most likely, unless you have taken other steps, you will answer N to this prompt
  • AsterionDB Administrator Username asteriondb_admin(default)
    • You can press Enter to accept the default or specify a custom value
  • Enter the AsterionDB Administrator Password
You can rerun the update script if you feel that you have entered a value (i.e.your password) incorrectly.
It is important to remember that the /home/asterion/asterion/oracle/admin/installSettings.sh file contains sensitive information – your DBA username and password as well as your AsterionDB administrator username and password. This file will be deleted by the installation script after AsterionDB has been installed.

Apply The Configuration And Install AsterionDB

The final step will install the database schema objects and start the AsterionDB services (i.e. DbTwig, DbObscura & DbStreamer).  To complete the installation use the following command:
				
					./applyConfig.sh
				
			

The installation process does not take long. Upon successfully installing AsterionDB, the script will delete the installSettings.sh file. The script will also ask you if you want to run the post-install cleanup script which will remove installation artifacts that are no longer needed.

What To Do If Something Goes Wrong

This installation process is fairly straightforward and there should not be too many ways in which things can fail.  Most failures can be attributed to an improper network setup (regional subnets only), copy/paste errors, invalid passwords and so forth.

If necessary, you can delete the appropriate component (e.g. load balancer, compute node) and start over.

If an error occurs in the apply step, you may have to delete the schema users.  The default user names that you will have to drop are:

  • asteriondb_dgbunker
  • asteriondb_runtime
  • dbtwig
  • dbtwig_listener

Accessing Your Production AsterionDB Installation

You can now use browser to connect to your compute node to access the AsterionDB Web Application.  You will be presented with a login screen:

Login Screen - AsterionDB

Conclusion

Thank you for taking the time to work through this installation guide.  For additional information and documentation, please refer to our Users Guide located here (opens in a new window): AsterionDB User’s Guide