API Server Installation Guide

API Server Installation Guide

Installing fcdb-api on a Linux system with Apache.

Overview

The Fossil Calibration Database is architected as a PHP/MySQL application. A RESTful API application has been built in JavaScript, using node.js. It connects to the same MySQL database as the PHP web application, but provides structured data in JSON and CSV formats. While this API application is not part of the PHP codebase, it can be easily configured to run on the same host and transparently handle requests to the same web server.

This is accomplished by

1. Installing required software (Node.js and its package manager)
2. Configuring the fcdb-api application as an init.d service.
3. Connecting Apache to fcdb-api using Apache's mod_proxy.

Requirements

1. FossilCalibrations - for its mysql database
2. node.js - Tested with v0.10.33.
3. npm - Tested with 1.3.6.
4. A linux system that supports init.d scripts - Tested with CentOS 6.6
5. Apache 2 with mod_proxy - Tested with 2.2.15

Installing fcdb-api

1. Install node and npm using your system's package manager (e.g. yum or apt-get). Tested on CentOS with node v.10.33 and npm 1.3.6. Both from EPEL

2. Create a dedicated API user account in your MySQL server. Grant read and execute access to the FossilCalibration database and set a password:

    $ mysql -u root -p
    mysql> create user api;
    mysql> grant select, execute on FossilCalibration.* to api;
    mysql> exit
    $ mysql -u api FossilCalibration
    mysql> set password=password('secret');
    mysql> exit
   

3. Using npm, install the forever package globally (globally means available system-wide, instead of in the local node_modules directory).

    $ sudo npm install -g forever 
   

4. Checkout the fcdb-api git repository:

    $ git clone https://github.com/NESCent/fcdb-api.git
   

5. Install local npm packages required by fcdb-api. These are not installed globally, but will be downloaded to fcdb-api/node_modules:

    $ cd fcdb-api
    $ npm install
   

6. Set the database connection info and credentials. This can be done by creating a config file:

    cat <<- EOF > /home/fcdb/fcdb-api/.fcdb-api-config
    export PORT=3000 # Port that node should use for incoming connections
    export FCDB_MYSQL_USER="api" # MySQL api user created above
    export FCDB_MYSQL_PASSWORD="<password here>" # MySQL api password created above
    export FCDB_MYSQL_PORT=3306 # MySQL server port
    export FCDB_MYSQL_HOST=127.0.0.1 # MySQL server address
    EOF
   

Credentials can also be placed directly in the fcdb-api/config/config.js file, but this is discouraged since it could easily be committed to version control.

6. Place the Example init script in /etc/init.d/fcdb-api, updating path to pidFile, logFile, nodeApp, config, and foreverApp to suit your system. This script was based on one created with initd-forever (initd-forever -a /data/webapps/fcdb-api/server.js -l /var/log/fcdb-api.log -n fcdb-api -f /usr/bin/forever)

7. Enable the init.d script with chkconfig:

    sudo chkconfig --add fcdb-api
   

8. Start fcdb-api:

    sudo service fcdb-api start
   

9. The API server is now running on the port specified in the config file (or 8081 if not specified).

10. Verify the API is running with curl or similar:

    $ curl http://localhost:3000/api/v1/calibrations/126
    {"id":126,"nodeName":... }
    

If you get an error about connecting to host, check to see if the service is installed correctly and running. If you get an error in JSON format, check the config file and MySQL account.

To integrate with Apache, continue to the next section.

Configuring Apache

1. Ensure that mod_proxy and mod_http_proxy are enabled in your Apache config (e.g. /etc/httpd/httpd.conf).

2. Edit your config for the Fossil Calibrations site (e.g. site-specific at/etc/httpd/conf.d/fcdb.conf) to pass the /api path from Apache to http://localhost:3000/api:

    <VirtualHost *:80>
      ...
      DocumentRoot /data/webapps/FossilCalibrations
      ServerName www.fossilcalibrations.org
      <Location />
        ...
      </Location>
      <Location /api>
        ProxyPass http://localhost:3000/api
        ProxyPassReverse http://localhost:3000/api
      </Location>
    </VirtualHost>
   

3. Do the same for the SSL version of the site, if separate.

4. On systems with SELinux enforcing, httpd may not be able to connect to other network services by default. This can be changed with:

    $ sudo togglesebool httpd_can_network_connect
   

5. Restart or reload apache

    $ sudo service httpd reload
   

6. Verify the apache server is proxying fcdb-api successfully with curl or a web browser:

    $ curl http://fossilcalibrations.org/api/v1/calibrations/126
    {"id":126,"nodeName":... }