f BeAPI API Framework - Documentation / Installation

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:

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:

  1. Use the following commands in a shell to create you local config directory:
    mkdir ~/.beapi
    cd ~/.beapi
    mkdir ~/.beapi/.iostate

  2. Next move all files marked above in your 'grails-app/conf' directory (see above) to your newly created '~/.beapi/' directory.

  3. 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:

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

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

  3. Next move all files marked above in your 'grails-app/conf' directory (see above) to your newly created '/home/beapi/.beapi/' directory

  4. Next move all files marked above in your 'src/iostate' directory (see above) to your newly created '/home/beapi/.beapi/.iostate' directory'

  5. Next, change permissions on those files:
    sudo chmod -R 755 /home/beapi/.beapi

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

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

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

  9. Finally, we create the bash script to call your service. First, we make the file:
    
    sudo nano /usr/share/beapi/beapi
                              

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

  11. Now set proper permissions on the files in '/usr/share/beapi':
    
    chown beapi /usr/share/beapi/*
    chmod 755 /usr/share/beapi/*
                              

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

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