@stelladoradus/device-transmission-api v1.0.51

Application API

Development

Use the following npm tasks while working on the application:

• npm build to build the application and output the redistributables into /dist folder
• npm watch to continuously build the application as you edit it
• npm start to launch the built application
• npm dev to combine the above - the sources will be rebuilt as you edit them and the server will be restarted automatically

Running the API on EC2 instance

The application is deployed to on EC2 to /home/ubuntu/stella-doradus folder. Create folder /home/ubuntu/stella-doradus and initialize as NodeJS project:

cd ~
mkdir stella-doradus
cd stella-doradus
npm init

Install the API as NodeJS dependency by running

npm install @stelladoradus/device-transmission-api

Create shared application cofiguration in ./configuration subfolder. Configuration can be found in ./node_modules/@stelladoradus/device-transmission-api/dist/configuration but it's better to have it outside. It's easier to find this way, and it will be shared by other applications such as Job Monitor.

Run the application under NodeJS process manager pm2 by running

pm2 start ./node_modules/@stelladoradus/device-transmission-api --name api -- -e staging -c ../../../../configuration -

The above example will register it as PM2 process named api and will execute it using configuration from ./configuration folder under staging environment. This means that settings from configuration.staging.js file will be used.

Management of the API on EC2 instance

All operations on the running API should be performed with pm2 interface.

To see the currently running NodeJS processes controlled by pm, run

pm2 ls

If API hasn't been started yet, it will not be listed. You need to start it first with the above command. For convenience, there's an alias defined in .bashrc, so you can start the API by running:

api-start

Once the API process is running and controlled by PM2, to stop, start again and restart the API use the following commands:

pm2 stop api
pm2 start api
pm2 restart api

To watch application log live and to flush the logs, run

pm2 logs api
pm2 logs api --lines 100
pm2 flush api

Automatic startup on EC2 instance reboot

The application has been configured to automatically start on reboot using pm2 as described at https://medium.com/@nishankjaintdk/setting-up-a-node-js-app-on-a-linux-ami-on-an-aws-ec2-instance-with-nginx-59cbc1bcc68c. We've executed the following commands:

pm2 startup
pm2 save

The first command instructs how to create a systemd service wrapper which will take care of starting pm2 automatically on instance reboot. The details of the service can be found in a systemd service file at /etc/systemd/system/pm2-ubuntu.service.

The second command stored the currently running pm2 processes in /home/ubuntu/.pm2/dump.pm2, so that pm2 knows what to start automatically when it's run on instance reboot.

AWS API Gateway

The API is deployed to AWS EC2 instance and shielded with API Gateway, which handles such concerns as HTTPS and CORS. The gateway is nearly transparent, except one thing - passing through the binary uploads. By defaults the binary content is not directly allowed and API Gateway encodes it before handling over to the API. To allow undisturbed passing through of the uploaded files, additional media types need to be permitted in the API gateway:

1. Go to API gateway in AWS console
2. Open Settings tab
3. Under Binary Media Types add:

• multipart/form-data
• application/octet-stream

4. Open Resources tab
5. Open Actions dropdown and run Deploy action

API Configuration

When running locally during development, configuration is found by default in ./configuration folder relative to the executable of the application.

It is possible to point the application to use a different configuration folder, by passing it as -c runtime parameter. The folder has to be a path relative to the application executable. For example, when running on EC2, we force the applications (API and Monitor) to use a shared configuration folder in /home/ubuntu/stella-doradus/configuration by passing -c ../../../../configuration to the API process.

Configuration used by the application is resolved by merging default settings from configuration.default.js with environment-specific settings. On development machines this will be configuration.development.js, on AWS staging environment this will be configuration.staging.js and on AWS production environment this will be configuration.production.js file. One can specify the environment used by the application by setting NODE_ENV variable or by passing it as -e parameter when running the application.

From API perspective, the following settings are applicable:

• logging - allows changing default log level across the application
• api - controls the working of the API module: host, port, external URL, CORS settings etc.
• storage - controls the storage parameters - database where upload jobs are stored and file storage where the uploaded files are kept

Refer to configuration.default.js for detailed description of all configuration parameters.