On Premises Installation Guide
Table of Contents
Introduction
The purpose of guide is to show you how to install AsterionDB on premises, or any situation where the AsterionDB Marketplace Image is not available.
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 Installation Guide 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. 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 v7.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:
- 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.
Overview
The general outline of steps we will be taking are:
- Obtain the SYSDBA username and password, the DBA username and password and the database connection strings (CDB & PDB) for an instance of the Oracle database
- Create a compute instance based on OracleLinux 7.9
- Connect to the compute instance
- Setup the compute instance to install AsterionDB
- Download and install AsterionDB on the compute instance
- Update the configuration settings
- Apply the configuration settings
- Access your production system
The Installation Process
Here are the steps we will take to install AsterionDB.
Gather Required Database Information
As previously mentioned, AsterionDB’s primary requirement is an Oracle Database. We will need the following information:
- SYSDBA username and password. This is needed in order to setup a target PDB with necessary privileges and logic that enable advanced security capabilities.
- DBA username and password for the target PDB. AsterionDB’s installation is driven using the DBA account.
- Database connection string or a tnsnames.ora entry value that points to the container database (CDB)
- Database connection string or a tnsnames.ora entry value that points to the target PDB
Create and Setup The Compute Node
We use OralceLinux 7.9 for our compute nodes. The compute node runs in as little as 1GB of RAM. Disk storage requirements are minimal, sans log files; 1GB is fine.
The AsterionDB compute node hosts the middle-tier listener, the web application and framework components. From the compute node, execute these commands:
sudo bash
yum install -y docker-engine
Start up docker:
systemctl start docker
We’ve seen some instances where docker-engine is not available due to misconfigured repo’s. If that is the case, here is the appropriate workaround:
yum install -y yum-utils zip unzip
yum-config-manager --enable ol7_optional_latest
yum-config-manager --enable ol7_addons
yum install -y oraclelinux-developer-release-el7
yum-config-manager --enable ol7_developer
yum install -y docker-engine
We use docker to deliver scripts that setup the compute node and download the AsterionDB software. Use this command to execute the setup script:
docker container run --rm asteriondb/install setup | bash -s
If you’d like to see what this script does, this variant of the above docker command will create a setup.sh script file:
docker container run --rm asteriondb/install setup >setup.sh
The setup script will create an O/S account for ‘asterion’. If you need to, set a password for the asterion account:
passwd asterion
Switch from sudo to the asterion user and execute the download script. Notice how we are exiting and reconnecting to pick-up the environment settings that the download script will make:
su -l asterion
docker container run --rm asteriondb/install download | bash -s
exit
su -l asteriondb
Establish Connection Between Compute Node and Database
cd /usr/lib/oracle/21/client64/lib/network
Create entries for your CDB and PDB and use sqlplus to verify that you can connect to both.
Alternatively, you can use standard Oracle connect-string syntax (i.e. host:port/service – your.host.computer:1521/asteriondb-instance).
Set The TWO_TASK and ORACLE_SID Environment Variables
export TWO_TASK=your_pdb
export ORACLE_SID=your_cdb
You will want to exit out and reconnect as asterion again to pick up the new environment variable settings.
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
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
./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:
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