master: {}[https://travis-ci.org/oveits/ProvisioningEngine]

development branch: {}[https://travis-ci.org/oveits/ProvisioningEngine]

== README This README documents describes the purpose of the software and describes the steps are necessary to get the Provisioning Portal up and running.

=== Purpose This ProvisioningEngine / ProvisioningPortal is a Proof of Concept that shows how to manage target systems (in our case VoIP & UC servers) and help administrators to provision Customers, Sites and Users on the target systems.

Check out a running example on https://provisioningengine.herokuapp.com/, a demo that is running with simulated target systems.

For demo purposes, the SW can be run without the Apache Camel module (see below) in simulation mode. An in-built mock service will simulate the answers of the Apache Camel service. Both, synchronous (i.e. foreground mode) or asynchronous mode (i.e. background mode) are possible in simulation mode.

In real live, the ProvisioningEngine uses background jobs to perform the provisioning tasks on VoIP, Voice Mail and Unified Communications systems. The background jobs are managed from the "Provisioning Tasks" tab.

In production, an Apache Camel based connector (private; not published here) is used as connector module for to

• manage configuration templates (SSH scripts, mass import files, SPML and SOAP packet templates)
• perform scripted remote creation and deletion of customers, sites and users
• access target system using SOAP/XML and SPML interfaces for reading, verifying and altering the configuration of the target systems.

=== Installation on Windows or Linux

• prerequisites:
  • rails v4 is installed
  • ruby v2 is installed
  • in simulation mode (default), the ProvisioningEngine can run standalone. In production, the Apache Camel based ProvisioningEngine (private SW) is needed as connector.
• download:
  • git clone https://github.com/oveits/ProvisioningEngine/tree/simulation_improvements ProvisioningPortal
• cd ProvisioningPortal
• rake db:migrate
• optional: allow background jobs (i.e. asynchronous mode):
  • cd config
  • cp application.yml.example application.yml # if not done already
  • edit application.yml:
  • WEBPORTAL_ASYNC_MODE: "true"
  • restart the web server after each change (e.g. (base dir)/stopWebPortal.sh and (base dir)/startWebPortal.sh on Linux)
  • On Linux, use the './stop; ./start' shell scripts in the application root (this will restart both, the web server as well as the background jobs)
  • On Windows, use the 'start.bat' script, and start delayed jobs on a separate window using 'bundle exec rake jobs:work'
  • On Heroku, the server is startet automatically, but you need to start the background jobs via heroku toolbelt using 'heroku run rake jobs:work' in a separate Window (temporary; for demo purposes; see also below) or start the background job permanently via the Heroku web page.
• optional: change configuration for non-simulation mode (requires Apache Camel Module, not part of this SW):
  • cd config
  • cp application.yml.example application.yml # if not done already
  • edit application.yml
  • adapt PROVISIONINGENGINE_CAMEL_URL to point to you Apache Camel ProvisioningEngine adapter (not part of this SW, please ask the author)
  • restart the web server after each change (e.g. (base dir)/stopWebPortal.sh and (base dir)/startWebPortal.sh on Linux)

=== Installation on Nitrous.IO (i.e. a cloud based development platform)

• on www.nitrous.io, create a box with minimum requirements
• open IDE
• in the console:
  • cd workspace
  • git clone https://github.com/oveits/ProvisioningEngine ProvisioningEngine
  • cd ProvisioningEngine
  • git status
  • git checkout -b nitrous
  • rake db:migrate RAILS_ENV=development
  • rails s &
  • cp config/application.yml.example config/application.yml
  • edit the file config/application.yml according to your needs
  • start Web Server, see below
  • commit changes to git:
  • first time use:
    • git config --global user.email "you@example.com"
    • git config --global user.name "Your Name"
  • git add .
  • git commit -am "description of the change"
• menu -> Preview -> Port 3000

=== Start the Web server

• start web server on Windows on port 80 (as an example):
  • cd ProvisioningPortal # the root of the SW, as downloaded via git clone above
  • rails s -p 80 --- or as daemon: rails s -d -p 80 (works also on nitrous.io, if you omit the -p 80, so port 3000 is used)
  • rake jobs:work # for starting the background processes (based on the "delayed_job_active_record" gem)
  • or run delayed_jobs as daemon:
  • first time install:
    • add gem "daemon" to Gemfile
    • bundle install
    • rails generate delayed_job
  • then start/stop daemon by: bin/delayed_job start/stop (works also on nitrous.io)
• start web server on Linux on port 80:
  • cd ProvisioningPortal # the root of the SW, as downloaded via git clone above
  • ./start # will start both, the web server and the delayed_jobs in the background and will append the logs to /var/log/WebPortal.log
• open a browser and connect to URL = http://localhost[:port]/ # port is needed, if another port than 80 was chosen expected result: redirection to http://localhost[:port]/customers, showing a list of configured customers (expected to be empty at this point).

=== Test Execution

• rake db:migrate RAILS_ENV=test
• on Linux:
  • change configuration in /spec/requests/provisioningobjects_spec.rb, if needed
  • ./startTests [-e "optional pattern"]
• on Windows:
  • bundle exec spork # for speeding up rspec test initialization
  • start single test or set of tests matching a pattern (--drb needed for spork speedup), e.g.:
  • bundle exec rspec --drb spec/requests/provisioningobjects_spec.rb -e "with valid information should create a provisioning task with action"
  • start all tests:
  • bundle exec rspec --drb spec/requests/provisioningobjects_spec.rb

== Running the Web Service on Heroku (optional) == You can run a copy of the server on the Heroku's PaaS cloud. In our case, Heroku is used to run the server as a demo on https://salty-peak-4964.herokuapp.com/, which is always available on Internet. Note that the web server often 'sleeps', but it will wake up automatically, when a packet is directed to it. This is, why the first access might need a minute, or so, for the service to react, but subsequent queries run at normal speed.

• prerequisites:
  • you need a heroku account
  • heroku toolbelt must be installed

    if not done already in the projects root folder:

  • heroku create

    elsif already created, attach the project to an existing heroku project:

  • heroku git:remote -a salty-peak-4964 where salty-peak-4964 is the existing heroku app (with heroku toolbelt, issue the command 'heroku apps' to see a list of your heroku apps)

    else you need to specify --app after each heroku command (does not work for 'git push heroku', though):

  • heroku --app salty-peak-4964 # where in this example, salty-peak-4964 is the heroku app found via 'heroku apps'

    end

• if the Heroku app is not configured to automatically deploy after each git push, you need to trigger it manually:
  • git push heroku # or
  • git push heroku :master #, if you are not on the master branch
• heroku apps
• heroku run rake db:migrate [--app # the --app option is needed only, if your local app is not attached to the project with the 'heroku create' or 'heroku git:remote' command, see above] e.g. 'heroku run rake db:migrate --app salty-peak-4964'
  • (optional: Installation process for automatic migrations on Heroku: Note: on heroku app salty-peak-4964, I have installed multi-buildpacks that automatically migrates at each deploy (see http://gunpowderlabs.com/blog/automatically-run-migrations-when-deploying-to-heroku/)
    • installation process (one time per app): (obsolete:)
    • create .buildpacks in root directory of your app with following content (do not use comments in the file, this has caused the build processes to fail): https://github.com/heroku/heroku-buildpack-ruby https://github.com/gunpowderlabs/buildpack-ruby-db-migrate.git

    • (deprecated) for your heroku app, perform:

      heroku buildpacks:set https://github.com/ddollar/heroku-buildpack-multi.git --app salty-peak-4964

      (exchange salty-peak-4964 by your app name)

      (replaced by)

    • define buildpacks: heroku buildpacks:set heroku/ruby

      needed for automatic db:migrate:

      heroku buildpacks:add https://github.com/gunpowderlabs/buildpack-ruby-rake-deploy-tasks heroku config:set DEPLOY_TASKS='db:migrate cache:clear'

    • if the .buildpack was already present (i.e. no change made to any file):
      • git push heroku
    • else
      • git add .
      • git commit -am "added automatic db:migrate support via buildpack"
      • git push
      • git push heroku
    • end
• If you need background jobs (i.e. if you have specified WEBPORTAL_ASYNC_MODE: "true" in (app-root)/config/application.yml:
  • heroku run rake jobs:work # this will block the CMD/terminal window, so for the next command, you will need a new CMD/terminal window:
• heroku open # this will open a browser with the correct link
• Active Admin
  • is currently used for manipulation of system wide variables only.
  • For initialization, perform the following step on the Linux shell: in the app's root folder, type:
    • rake db:seed this will create the default Active Admin user admin@example.com with password=password.
    • add your own Admin user and password using the Active Admin console on https://localhost:3000/admin/admin_users (adapt URL name and port, if needed)
    • remove the admin@example.com user

=== Developers Info: Commit & Production

• git general setup (first time use of git on the machine):
  • git config --global user.email "you@example.com"
  • git config --global user.name "Your Name"
  • optional: set up git, so it does not ask for the username anymore:
  • if you are bound to use HTTPS instead of SSH, you can set the local repository .git/config file to url = https://oveits@ProvisioningEngine.git # replace oveits by your own git repository login name
  • if you are allowed to use SSH and do not want to enter the password, try url = git@github.com:oveits/ProvisioningEngine.git # replace oveits by your own git repository login name
• download via git:
  • preparation: if behind proxy (e.g.: 172.28.12.5:8080):
  • SET HTTP_PROXY=http://172.28.12.5:8080
  • or
  • initial download: master branch: git clone https://oveits@ProvisioningEngine.git
  • update from remote: git pull
  • download of additional branch (here: branch 'development'): git checkout -b development origin/development (see http://www.wetware.co.nz/2009/07/pull-a-git-branch-from-remote/; via google you will find other possibilites with drawbacks; this seems to b e the best possibility)
• cd e.g. on my Windows machine: cd /d F:\veits\RubyOnRails\ProvisioningPortalvx.x.x
• best practice: perform automatic tests, see "Test Execution"
• review: which files will be changed?
  • git status
• review changes line by line:
  • git diff
• commit the changes in case the review was OK:
  • bundle exec rake assets:precompile # needed in production and/or heroku, if assets like css have changed.
  • git add .
  • git commit -m "description of the change"

    or only 'git commit' and edit longer description (recommended)

  • git push
  • optional:
  • git push heroku
    • only needed, in case your service runs on Heroku, and the Heroku project is not configured to automatically deploy from GitHub.
    • Prerequisite of manual deploy: and and your local repository is attached to Heroku (see below)
• git tagging:
  • only in case the automated tests (e.g. via travisCI) were successful; e.g.:
  • git tag -a v0.5.18 -m "tested in simulation mode" or
  • git tag -a v0.5.19 -m "tested in pre-production"
  • then: git push --tags
• in case another local repository has changed the remote git repository: synchronize local git with remote git repository:
  • git pull

=== NginX HTTPS Offload (optional) In the productive environment, NginX is used for following purposes:

1. Offload of HTTPS
2. Allow more than one web service to use the same IP address in our case, e.g. /customers is redirected to the productive web service running on TCP port 3000, while /dev/customers is redirected to a development branch of the web service running on TCP port 3001

How to set up NginX:

• sudo apt-get update
• sudo apt-get install nginx
• cd /etc/nginx
• sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/cert.key -out /etc/nginx/cert.pem
• change config: sudo vi /etc/nginx/sites-enabled/default
• observe error logs: sudo tail -F /var/log/nginx/error.log
• in other terminal: sudo service nginx start

=== Tipps

• Pre-view this rdoc:
  1. rdoc README.rdoc -o ./tmp/doc
  2. open (application root)/tmp/doc/README_rdoc.html in a browser