How to Deploy a WBC Server

From Whole Brain Catalog

Jump to: navigation, search

Contents

[edit] Overview

This procedure will

  • Prepare the target server host
  • Package wbc-server for deployment
  • Deploy it to the target server
  • Start the server
  • Test it

[edit] Server Setup

  • One time only
  • Requires root access

⇒ Set up dedicated 'wbc' user

⇒ Set up sudo privileges

⇒ Set up JAVA_HOME environment variable

⇒ Make server directory: /usr/local/wbc/

⇒ Change owner and group of the server directory to 'wbc'

⇒ Create /etc/init.d/wbcserver script for running the server as a service

[edit] Deployment Variations

There are two main components to a fully functioning wBC server:

  • The server software code and associated configuration files
  • The affiliated database and its associated data files

With these WBC server components there are several possible deployment options:

  1. Deploying new server code but using the old existing database and data files
  2. Rebuilding the database and data files but using existing server code
  3. Deploying new server code and building a new database and data files

The deployment procedures will vary based on the deployment option you choose.

[edit] Deployed Server Footprint

Service script: 

/etc/init.d/wbcserver

Server directories and files ("x.x.x" represents the version identifier) 

/usr/local/wbc/

    wbc-server-x.x.x/

        bin/     -- various execution scripts
            installDb.sh
            quickTestServer.sh
            snapshotData.sh
            startserver.sh
            stopserver.sh
            [others that may be under development]
    
        conf/    -- runtime configuration files
            favicon.ico
            hibernate.properties
            log4j.properties
            wbcserver.properties
            wholeWBCState.xml

        data/    -- data files
    
        db/      -- HSQL database files
            wbcdb.lck
            wbcdb.log
            wbcdb.properties
            wbcdb.script
    
        lib/     -- jar files (generally just one jar with server code and dependencies)
            wbc-server-x.x.x-with-dep.jar
    
        logs/    -- log files
            startuplog.MM-DD-YY    -- sysout/syserr redirected to this file (month-day-year)
            wbcserver.log          -- current active log file for logger statements
            wbcserver.log.N        -- N=0..n -- older generations of log files
        
    wbcserver    -- (no hyphen) symlink to /usr/local/wbc/wbc-server-x.x.x

[edit] Notes About the Footprint

There may be several wbc-server-x.x.x directories under .../wbc/, for example,

  • wbc-server-1.2.3/
  • wbc-server-1.2.4/
  • wbc-server-1.3.0/

The "active" one is the one to which the symlink "wbcserver" (no hyphen) points.

There may be several wbc-server-x.x.x-*.tar.gz files also. These are files deployed to the server.

Using the symlinks it's easy to keep several versions on the server and quickly switch to a new one or roll back to a previous one. The server down time during cutover can be minimized by loading and unzipping the files while the server is running. When a new version is in place and ready you can

  • Down the server
  • Switch the symlink from previous to new version
  • Up the server
  • Test the new version
  • If any problems,
    • Down the server
    • Revert the symlink
    • Up the server
    • Investigate the problem while the server is back in a stable version

[edit] Configuration Files

[edit] hibernate.properties

  • JDBC connection parameters for the database the server connects to
    • These MUST be checked!
  • Connection pool parameters
    • These may be altered to tune server and database performance
  • Other standard hibernate properties
    • Shouldn't generally need to alter these

[edit] log4j.properties

  • Root logging level
  • Selective package/class logging level overrides
  • Logging appenders
  • Other standard log4j properties

[edit] wbcserver.properties

  • Location of data files
    • Generally set to 'data/' relative path (see Deployed Server Footprint above)
  • Other miscellaneous server properties
    • Shouldn't generally need to alter these

[edit] Procedure: Deploy a Server

  • Follow this procedure to
    • Deploy new server code
    • Deploy new database content and data files
    • Deploy both server code and data
  • Some steps are skipped depending on the type of deployment
  • The lines that begin with "⇒" represent discrete operations to be manually performed.
[edit] Config file checks
  • Files in wbc-server/src/main/resources

⇒ hibernate.properties: Pointing to desired database server?

⇒ log4j.properties: No CONSOLE logging?

[edit] Clean, build, assemble the project

⇒ In Eclipse project wbc-server, select the wbc-server project, right click > Run As > Maven clean

⇒ In Eclipse project wbc-server, select the wbc-server project, right click > Run As > Maven install

⇒ In Eclipse project wbc-server, select the wbc-server project, right click > Run As > Maven assembly:assembly

⇒ Open a terminal on the system where you develop and compile

⇒ $ cd <eclipse-wbc-server-project>/target/

[edit] Copy the server deployment file to the target host
  • This will copy the server and data files tar files to the target host

⇒ $ scp wbc-server-x.x.x-server.tar.gz wbc@<target-host>:/usr/local/wbc/

[edit] Log on to the target host

⇒ $ ssh wbc@<target-host>

⇒ $ cd /usr/local/wbc/

[edit] Install and set up the server
  • Applicability: Code deployment -- skip this step if this is not a code change
  • Creates a directory wbc-server-x.x.x-server

⇒ $ tar xzf wbc-server-x.x.x-server.tar.gz

⇒ $ cd wbc-server-x.x.x/

⇒ $ ls -l

⇒ Check that you see directories: bin/, conf/, data/, db/, lib/, and logs/

⇒ $ less conf/log4j.properties: No CONSOLE logging?

⇒ $ cd ../

[edit] Stop the server

⇒ $ sudo /sbin/service wbcserver stop

[edit] Change the symlink from the old to the new server version
  • Applicability: Code deployment -- skip this step if this is not a code change

⇒ $ rm -i wbcserver

⇒ $ ln -s wbc-server-x.x.x/ wbcserver

[edit] Start the server

⇒ $ sudo /sbin/service wbcserver start

[edit] Test the Server
  • The <target-host> below usually does not require a port. If it does it would be <target-host>:<port>.
[edit] Test 1
  • This tests basic server responses to HTTP GET requests.

⇒ $ cd wbcserver/

⇒ $ bin/quickTestServer.sh

⇒ Look for a series of PASS and SUCCESS messages

[edit] Test 2
  • Run the WBC client (development version) and make sure it comes up

⇒ In a browser, run the "Latest development version" of the WBC client

⇒ Select the server to test

⇒ Check that the client comes up

[edit] Log off the server

⇒ $ exit

[edit] Procedure: Executing a Maven Release

  • Use this procedure if using the Maven Release Plug-in

⇒ Ensure configuration files (hibernate,properties and log4j.properties) are set as desired

⇒ Close out releaseNotes.txt

⇒ Do a final commit to SVN ("Final commit preparing for new release.")

⇒ Open a terminal window

⇒ $ cd <eclipse-workspace>/<project>/

⇒ $ mvn release:prepare

⇒ $ mvn release:perform

⇒ In Eclipse project wbc-server, select the wbc-server project's target/checkout/ directory, right click > Run As > Maven assembly:assembly

⇒ $ cd <eclipse-wbc-server-project>/target/checkout/target/

⇒ Update releaseNotes.txt for the new development version

[edit] Procedure: Update Database Content Only

  • Follow this procedure to
    • Replace the content of a database
  • Do not use this procedure for any other purpose
  • Data files remain untouched
  • The lines that begin with "⇒" represent discrete operations to be manually performed.
[edit] Rebuild a database and populate from an XML file
  • DESTRUCTIVE operation!
  • Wipes a database (drop tables)
  • Build the database schema (create tables)
  • Changes selected VARCHAR(255) columns to TEXT (alter tables)
    • This will only happen for MySQL databases
    • The affected columns are determined by the ALTER_STATEMENTS array in wbc-server/src/main/java/.../data/DatabaseMaintenance.java
  • Loads the database with data from an XML file
  • Takes about 3 minutes on standard databases
  • *** TODO *** I (Dave) intend to change this procedure so it runs on the server host
    • This will require
      • Placing the new wholeWBCState.xml file on the server
      • Running a simple script to run Populate on the server
    • This will avoid
      • Using Eclipse
      • Hibernate edit
      • Maven install
      • Any confusion about the correct database

⇒ In Eclipse wbc project, update from SVN to get the latest wholeWBCState.xml file

⇒ In Eclipse module wbc-server, edit src/main/resources/hibernate.properties to point to the desired database

⇒ In Eclipse, wbc-server directory, right click > Run As > Maven install

⇒ $ ssh wbc@<desired-server-host>

⇒ $ sudo /sbin/service wbcserver stop

⇒ In Eclipse module wbc-server, select src/main/java/.../util/PopulateDatabaseFromXML.java, right click > Run As > Java Application

⇒ In the dialog box, make sure you are pointing to the right database, then press OK or Cancel

⇒ $ sudo /sbin/service wbcserver stop

⇒ Test the server

⇒ $ exit

[edit] Snapshot a Server's Data

  • Creates a server- and date-stamped archive file
    • wbcData-<server-name>-YYMMDD=HHMM.tar.gz
  • The file contains
    • wholeWBCState.xml (exported from the database)
    • The corresponding set of data files
  • The file may be retrieved at any time
[edit] Log on to the server host

⇒ $ ssh wbc@<server-host>

⇒ $ cd /usr/local/wbc/

[edit] Run the snapshot program

⇒ $ wbcserver/bin/shapshotData.sh

[edit] Log off

⇒ $ exit

[edit] Push Development Server to Staging or Production

  • This procedure is used to "push" a
  1. development server (<from-server>) to a staging server (<to-server>)
  2. staging server (<from-server>) to a production server (<to-server>)
[edit] Check and clear disk space on the destination server

⇒ $ ssh wbc@<to-server>

⇒ $ cd /usr/local/wbc/

⇒ $ df

  • Remove any old zip, tar.gz, and directories to clear disk space
  • DESTRUCTIVE operations -- be careful!

⇒ $ rm -rf wbc-server-x.x.x

[edit] Copy the code and data files to the destination server
  • The 'from' and 'to' servers would be
  1. development and staging servers
  2. staging and production server

⇒ $ ssh wbc@<from-server>

⇒ $ scp wbc-server-x.x.x*.tar.gz wbc@<to-server>:/usr/local/wbc/

[edit] Install the new target server
  • Follow the procedure above starting with "Install and set up the server"
  • NOTE: It is especially important that you edit hibernate.properties to change the hibernate.connection.url property to point to the new target database

[edit] Controlling Server Write Operations

Write operations on the server include

  • Adding, changing, or deleting a data file
  • Inserting, updating, or deleting operation in the database

From the client perspective, server write operations are initiated via HTTP

  • PUTs
  • DELETEs
  • Those POSTs that ask the server to perform a write operation

The write operations can be enabled or disabled by settings in the conf/wbcserver.properties file. This file contains the following: 

can-add-data-files = false
can-change-data-files = false
can-delete-data-files = false
can-insert-datawrappers = false
can-insert-tangibles = false
can-update-tangibles = false
can-delete-tangibles = false
can-insert-users = false
can-update-users = false

A false value disables the operation while a true enables it.

If a disabled write operation is attempted from the client, the server will not perform the operation and will return a 403 (forbidden) status code.

[edit] Enabling or Disabling the Write Controls

  • Log on to the desired server via ssh
  • Change to the /usr/local/wbc/wbcserver directory
  • Edit the write control properties in the conf/wbcserver.properties file
  • Save the file
  • Restart the server with the command: sudo /sbin/service wbcserver restart
Retrieved from "http://wiki.wholebraincatalog.org/wiki/How_to_Deploy_a_WBC_Server"
Personal tools