Getting Started with AsterionDB®
Available on the Oracle Cloud Marketplace.
Click on the image to open our marketplace listing in a new window.
Watch the Companion Video
Table of Contents
Introduction
The purpose of this Getting Started Guide is to show you how easy it is to install AsterionDB. You can use AsterionDB with Oracle’s Always Free product offerings. This provides a powerful platform for individual use, evaluation, prototyping and software development. Oracle provides an Autonomous Database, 20GB of database storage, a compute instance and a load balancer in their Always Free tier.
Getting starting with AsterionDB on the Oracle Cloud Marketplace is easy. Experienced users can have a system up and running within 20 minutes.
For those that are new to the Oracle Cloud Infrastructure, AsterionDB is a great way to start learning.
Objective
This guide will walk you through the process of installing AsterionDB. The documentation includes instructions on creating a load balancer with secure SSL communication enabled using a DNS entry that you control. This process uses CertBot from LetsEncrypt, a popular certificate manager available for Linux. If you are unable to enroll a DNS entry you can still use AsterionDB with an SSH tunnel but this requires a higher level of expertise. Instructions for this are provided as well.
The installation will utilize the Oracle Cloud Free Tier. AsterionDB fits perfectly within the limitations of the Oracle Cloud Free Tier.
We will use an autonomous database, load balancer and a compute instance. By following this guide, the installation will be accessible on the public internet via the HTTPS protocol or by using a SSH and a tunnel. At no time will the installation be accessible via insecure means.
The resulting AsterionDB installation is intended for personal use and is not rated or supported for large scale production settings.
Prerequisites
These prerequisites will give you a good understanding of what 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.
This guide presumes that you have already created an account in the Oracle Cloud Infrastructure. Access the following link to create your account if you have not done so already:
https://www.oracle.com/cloud/free/
We will be working with the Oracle Autonomous Database and a corresponding AsterionDB Compute Instance. The compute instance runs all of the AsterionDB framework components as well as a JavaScript web application served by Nginx.
For Internet access, you must have access to a domain in which you can enroll a DNS entry to point to your compute instance. This is usually accomplished through a domain registrar where you use a webform to associate an IP address with a domain name (i.e. asteriondb.your-company-name.com). Instructions for making this entry are beyond the scope of this document. It is a prerequisite that you have the ability to create a domain name for your AsterionDB installation if you will be accessing the system over the public internet.
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:
- Create an Autonomous Database
- Open up the Cloud Shell
- Download and run the helper script
- Create a compute instance
- Connect to the compute instance
- Setup OCI CLI
- Run the load balancer setup script
- Update the configuration settings
- Apply the configuration settings
- Access your production system
The Installation Process
Here are the steps we will take to install The AsterionDB Digital Bunker.
Create an Autonomous Database
Oracle Cloud Infrastructure provides a wizard that will walk you through the steps to create an Autonomous database. AsterionDB is compatible with both versions of Autonomous – Transaction Processing and Data Warehouse. If you are just getting started, you can choose either one for now. Use this link to see a discussion on which version to choose (opens in a new window) Which Version of Autonomous?
The ‘Create an Autonomous’ link is located on the main OCI page’s Get Started tab, in the Launch Resources section. Be sure to select the Always Free configuration as shown in the following screen shot.
You will also need to provide a password for the ADMIN account. Oracle enforces strict passwords so you may want to save your password in a text file for quick and easy reference – you’re going to need it.
Open up the Oracle Cloud Shell
The OCI provides a built-in Cloud Shell that you can use to access the AsterionDB compute instance. Press the little console icon towards the top right side of the Oracle Console to open up the Cloud Shell. The icon looks like this:
The Cloud Shell opens up in the bottom third of your browser screen as shown in this screenshot:
Download and Run the AsterionDB Cloud Helper Script
We deliver a cloud installation helper script using Docker that you will run from the Cloud Shell. This helper script will perform some initial setup actions on the compute instance and install the wallet that enables connections to the database. Here is the Docker command to get the helper script:
docker container run --rm asteriondb/install helper | bash -s
The helper script will be downloaded to your home directory. Run the helper script from your Cloud Shell command prompt:
./helper.sh
The helper script will first ask you for your database OCID. In the screenshot above you can see how a link is provided in the General Information section that allows you to easily copy the OCID.
The helper script will then download the database wallet and check for existence of an RSA key-pair in the local Cloud Shell. If an RSA key-pair does not exist, one will be created for you with no password.
The helper script will display your public key and instruct you to create your AsterionDB Compute Instance.
Create the AsterionDB Compute Instance
An installable image for the compute instance is located in the Oracle Cloud Marketplace. Navigate to Cloud Marketplace –> All Applications and select AsterionDB in the publisher drop-down.
Click on the entry for the AsterionDB Zero Trust Platform and then click the Launch Instance button to start the creation process of a compute instance from the marketplace image.
Select your desired shape by pressing the Change Shape button. If you intend to use a free-tier compute instance, you will have to select the appropriate availability domain when selecting the shape; free-tier compute instances are not available in all availability domains. Furthermore, the free-tier shape is only available in the Specialty and Previous Generation shape series.
As mentioned, the Cloud Shell has printed out your public key. Paste the Cloud Shell’s public key in the section Add SSH Keys:
Power-User Tip: Add another key and paste the public RSA key from your local computer, if you have one. You will then be able to connect to the compute instance from your local computer.
Press the Create button to initiate the creation of the compute instance. Instance creation only takes a few minutes. Your screen will look like this after pressing the create button:
The IP address will become available and then the screen will turn green. Wait another two minutes or so for the startup process to fully complete and then return to the helper script running in the Cloud Shell. It will ask you to paste the IP address. When the IP address is available there will also be a link that will allow you to easily copy the value.
Press Enter once more, after waiting a sufficient amount of time for the compute instance’s startup process to finish (approximately 3 minutes) in order to complete the setup process.
Connect to the Compute Instance
These steps are to be taken if you intend to place your AsterionDB installation on the Web. Your alternative is to use SSH with a tunnel. See the section Connect Using an SSH Tunnel for more information.
From the Oracle Cloud Shell, type the following command to connect to your compute instance:
ssh asterion@ip.address
Install the Oracle Command Line Interface (CLI)
Note: We do not pre-install the Oracle CLI for security reasons. Please observe appropriate security procedures for user API keys on a compute node.
In order to create the load balancer in the next step, you will need to install the Oracle CLI. Execute the following command:
sudo yum install -y python36-oci-cli
If you would like to see a log file showing the following steps being taken, click on this link (opens in a new window): Installation Log
Run the CLI setup process with the following command:
oci setup config
Power-User Tip: The process described below creates and uploads an API key. If you already have an API key and know how to setup the CLI, you can skip this step.
The CLI setup process will ask you to provide/confirm the following:
- The location of the config file (accept the default)
- Your user OCID – Navigate to Identity & Security –> Users and select your username to find your OCID
- Your tennancy’s OCID – Navigate to Governance & Administration –> Tenancy Details to find your tenancy’s OCID
- Your region
Accept the default values for the remaining prompts (key location, password etc).
When the setup process completes you will upload your public API key to the OCI. Type (cat) out the API key (/home/asterion/.oci/oci_api_key_pub.pem) and copy the value into the paste buffer. Be careful that you do not copy any extraneous characters!
There are two different ways to add an API key, depending upon how your Oracle Cloud account has been provisioned. One way is to navigate to Identity & Security –> Users and select your username.
The other is to click on the ‘Profile’ icon at the far right and select ‘My Profile’. Here’s a screenshot:
Then select API Keys and press the Add API Key button.
Paste your public API key and add the value. The OCI will display your CLI configuration file settings. These setting were already made by the ‘oci setup config’ process so you can ignore the screen and complete the setup.
You can test your CLI setup by typing the following command:
oci iam compartment list
Setup the Load Balancer (for public access)
If you would like to see a log file showing the following steps being taken, click on this link (opens in a new window): Installation Log
These steps are to be taken if you intend to place your AsterionDB installation on the Web. Your alternative is to use SSH with a tunnel. See the section Connect Using an SSH Tunnel for more information.
We provide you with a script to assist in setting up a regional load balancer. You will need the following information to run the script:
- Your domain name (i.e. asteriondb.your-company-name.com)
- Your email address (required for Let’s Encrypt enrollment, so they can send you notices if necessary)
- The compartment OCID that the load balancer will be placed in
- The VCN regional subnet OCID that the load balancer will be created in – take note that the subnet is located under your VCN
You will also have to enroll the load balancer’s IP address in your DNS table. (Note: a description for this step is beyond the scope of this document)
Run the script by typing the following at the command prompt:
cd ~/asterion/oracle/admin/setupLoadBalancer
./setupLoadBalancer.sh
The setup script will ask you for the information listed above and ask you to select the load balancer shape. If you are using AsterionDB with Oracle’s Always Free Tier you can select the default value for minimum and maximum bandwidth, 10Mbs.
The script will pause after initially creating the load balancer and assigning a public IP address. You will use your internet registrar’s webform to associate your AsterionDB website address (i.e. asteriondb.your-company-name.com) with the load balancer’s public internet address.
Note: A proper DNS entry is required. The load balancer setup process will fail at the SSL Certificate step if the DNS entry is not available.
Check the Load Balancer Installation
At this point you will be able to bring up the AsterionDB pre-installation web page to verify that the load balancer, compute instance and Nginx are setup properly. Navigate to your load balancer’s DNS name (e.g. asteriondb.your-company-name.com). You should get the following screen:
Verify that the SSL certificate and HTTP redirect are properly working. Some browsers may require you to manually specify HTTP and port 80 in order to check HTTPS redirect (i.e. http://asteriondb.your-company-name.com:80).
Connect Using an SSH Tunnel
If you are unable to register a DNS entry and instead must use an SSH tunnel to access your AsterionDB installation, please follow these steps.
First, you will need to enable your local computer so that it can connect to the compute instance with SSH. You can do one of two things:
- Download your Oracle Cloud Shell’s private ssh-key and install it on your local computer. This is the power-user move.
- Generate an ssh-key pair on your local computer and upload the public key to the compute instance. Please see this link (opens in a new window) for information on how to configure your local computer for SSH access – Oracle Documentation Link
With SSH configured you can now connect using the following command:
ssh asterion@compute.node.ip.address -L 8080:localhost:8080
Note: you may need to add an option to specify the SSH key.
Complete the AsterionDB Installation
If you would like to see a log file showing the following steps being taken, click on this link (opens in a new window): Installation Log
You are now ready for the final step – installing AsterionDB in your database and starting up the services.
The first step is to update the installation configuration file. You will need to know the following:
- Your DBA username (e.g. ADMIN)
- Your DBA password
- Your domain name – the default is localhost:8080 but you will want to use your domain name (e.g. asteriondb.your-company-name.com)
The script will also prompt you to supply or confirm the following values:
- The database type (defaults to Autonomous)
- The database name
- The schema user name to use to hold the AsterionDB installation (defaults to asteriondb_dgbunker)
- A password to use for the schema user
- Confirm the use of SSL
- The application level user name to use as the administrator of the AsterionDB installation (defaults to asteriondb_admin but it can be any name you want, even yours)
- A password to use for the application level user
Use this command to update the installation configuration file:
cd ~/asterion/oracle/admin
./updateConfig.sh
You can rerun the update script if you feel that you have entered a value (i.e.your password) incorrectly.
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
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 return to the browser window that you used to check the load balancer or otherwise navigate to your domain name (e.g. asteriondb.your-company-name.com or localhost:8080) to access the AsterionDB Web Application. You will be presented with a login screen:
Login to AsterionDB using your application-level user name (i.e. asteriondb_admin) and your password. The main screen for the AsterionDB Web Application will appear:
When you first enter the web application you will be placed on the ‘Search’ tab. As you can see, there is no content yet.
Click on the ‘Upload’ tab:
When running against an Autonomous Database the following object (file) types will be enabled by default:
- Audio
- Images
- PDFs
- Videos
- Archives
- Text
Use the ‘Select Files’ button or drag-and-drop some content into the system:
Double-Click on an object and then select the viewer tab (for an object that can be displayed, like a PDF):
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