BeAPI API Framework Installation

Getting started with BeAPI is simple process. Below are the steps for installation and configuration of your Beapi API Automation Tool Suite...

Requirements

The BeAPI™ API Framework has the following project requirements:

Java 1.8 (or higher)
curl(sudo apt install curl): used for testing

Also make sure your USER_HOME/.grails/settings.groovy file looks lkike the following:


grails {
  profiles {
    repositories {
      maven {
        url =  "https://dl.bintray.com/orubel/profiles/"
        snapshotsEnabled = false
      }
      grailsCentral {
        url = "https://repo.grails.org/grails/core"
        snapshotsEnabled = true
      }
    }
  }
}

Quick Start Installation

To quickly get started on a new project, type the following command to create a new project with the Beapi Framework Installed:

grails create-app name_of_your_app --profile org.grails.profiles:beapi-profile:2.0.39

You should now have a project directory that looks something like this:

docs documentation
gradle gradle directory
grails-app directory for MVC of application
- commands gradle commands directory
- conf configuration directory
  - application.groovy application config file. DO NOT MOVE!!!
  - logback.groovy application log file. DO NOT MOVE!!!
  - beapi.groovy FILE TO BE MOVED TO '~/.beapi'
  - beapi.yml FILE TO BE MOVED TO '~/.beapi'
  - beapi_api.yml FILE TO BE MOVED TO '~/.beapi'
  - beapi_db.yml FILE TO BE MOVED TO '~/.beapi'
  - beapi_server.yml FILE TO BE MOVED TO '~/.beapi'
- controllers/net/nosegrind/apiframework application controllers folder
- domains/net/nosegrind/apiframework application domains folders
- i18n unused
- init Application initializtion folder
- jobs cronjobs folder
- services services folder
- views views folder
src src folder
- integration-test test folder
- iostate io-state folder
  - Apidoc.json FILE TO BE MOVED TO '~/.beapi/.iostate'
  - Hook.json FILE TO BE MOVED TO '~/.beapi/.iostate'
  - IOState.json FILE TO BE MOVED TO '~/.beapi/.iostate'
  - Person.json FILE TO BE MOVED TO '~/.beapi/.iostate'
  - PersonRole.json FILE TO BE MOVED TO '~/.beapi/.iostate'
  - Role.json FILE TO BE MOVED TO '~/.beapi/.iostate'
  - Stat.json FILE TO BE MOVED TO '~/.beapi/.iostate'
  - Test.json FILE TO BE MOVED TO '~/.beapi/.iostate'
- main application folder
build.gradle gradle build file
gradle.properties gradle properties file

Move Configuration Files

Once you have created your project, you will need to create a file in your home directory for your configuration files:

Use the following commands in a shell to create you local config directory:
mkdir ~/.beapi cd ~/.beapi mkdir ~/.beapi/.iostate
Next move all files marked above in your 'grails-app/conf' directory (see above) to your newly created '~/.beapi/' directory.
Next move all files marked above in your 'src/iostate' directory (see above) to your newly created '~/.beapi/.iostate' directory.

Now you are setup and can start configuring your environment...

Running As A Service

Once you have created your project, you will need to create a file in your home directory for your configuration files:

First create a user that the app will run under:
sudo adduser beapi

Next, use the following commands in a shell to create you local config directory and change ownership to the newly created user:

mkdir /home/beapi/.beapi
mkdir /home/beapi/.beapi/.iostate
sudo chown -R beapi /home/beapi/.beapi
sudo chgrp -R beapi /home/beapi/.beapi

Next move all files marked above in your 'grails-app/conf' directory (see above) to your newly created '/home/beapi/.beapi/' directory
Next move all files marked above in your 'src/iostate' directory (see above) to your newly created '/home/beapi/.beapi/.iostate' directory'
Next, change permissions on those files:
sudo chmod -R 755 /home/beapi/.beapi

Next, create the directory for the executable and move the JAR:

sudo mkdir /usr/share/beapi
sudo mv beapi-all-in-one-X.X.XX.jar /usr/share/beapi

Now we create the service that calls the executable. Run the following command to open a text editor:
sudo nano /etc/systemd/system/beapi.service

Now copy and paste the following into the text editor and then EXIT and SAVE:


[Unit]
Description=BeAPI API Service
[Service]
User=beapi
# The configuration file application.properties should be here:
#change this to your workspace
WorkingDirectory=/home/beapi
#path to executable.
#executable is a bash script which calls jar file
ExecStart=/usr/share/beapi/beapi
SuccessExitStatus=143
TimeoutStopSec=10
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target

Finally, we create the bash script to call your service. First, we make the file:


sudo nano /usr/share/beapi/beapi

And then we copy and paste the following:


#!/bin/bash

MAIN_CLASS=/usr/share/beapi/beapi-all-in-one-X.X.XX.jar
ARGS="-Xms1024m -Xmx2048m -XX:PermSize=64m -XX:MaxPermSize=128m -XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC -XX:+CMSIncrementalMode -XX:+CMSIncrementalPacing -XX:CMSIncrementalDutyCycle=10 -XX:+UseParNewGC -XX:MaxGCPauseMillis=100 -XX:MaxGCMinorPauseMillis=50 -server"

exec java $MAIN_CLASS $ARGS

Now set proper permissions on the files in '/usr/share/beapi':


chown beapi /usr/share/beapi/*
chmod 755 /usr/share/beapi/*

Last (but not least) initialize and start up your service:


sudo systemctl daemon-reload
sudo systemctl enable beapi.service
sudo systemctl start beapi
sudo systemctl status beapi

If there are ANY ISSUES with your service starting, you can view them in the logs with the following:
sudo journalctl --unit=beapi

Now you are setup and can start configuring your environment...

Troubleshooting

Make sure you have proper READ/WRITE/EXECUTE(755) for the files in ~/.beapi/ and ~/.beapi/.iostate
Make sure you have matching named Controllers/Domains for all IO State files
If you want to use a version of Java HIGHER than 1.8, change 'sourceCompatibility' in build.gradle