An engine must be built (i.e. pio build) and trained (i.e. pio train) before it can be deployed as a web service.

The engine server is not protected by authentication, and the instructions below assume deployment in a trusted environment.

Deploying an Engine the First Time

After you have downloaded an Engine Template, you can deploy it with these steps:

  1. Run pio app new **your-app-name-here** and specify the appName used in the template's engine.json file (you can set it there to your preference).
  2. Run pio build to update the engine
  3. Run pio train to train a predictive model with training data
  4. Run pio deploy to deploy the engine as a service

See here to know details of command-line interface for the engine server.

A deployed engine listens to port 8000 by default. Your application can send query to retrieve prediction in real-time through the REST interface.

Note: a new engine deployed as above will have no data to start with. Your engine may come with a data/ directory with some sample data that you can import, not all have this. Check the quickstart instructions for your template.

Update Model with New Data

You probably want to update the trained predictive model with newly collected data regularly. To do so, run the pio train and pio deploy commands again:

$ pio train
$ pio deploy

For example, if you want to re-train the model every day, you may add this to your crontab:

0 0 * * *   $PIO_HOME/bin/pio train; $PIO_HOME/bin/pio deploy

where $PIO_HOME is the installation path of PredictionIO. See Retrain and Deploy Script below for a script ready for customization.

Specify a Different Engine Port

By default, pio deploy deploys an engine on port 8000.

You can specify another port with an --port argument. For example, to deploy on port 8123

pio deploy --port 8123

You can also specify the binding IP with --ip, which is set to localhost if not specified. For example:

pio deploy --port 8123 --ip

Retrain and Deploy Script

A retrain and deploy script is available in the examples/redeploy-script directory.

To use the script, copy as, as (say) MyEngine_Redeploy_(production).sh (Name of the script will appear as title of email) and put both files under the scripts/ directory of your engine. Then, modify the settings inside both file, filling in details like PIO_HOME, LOG_DIR, TARGET_EMAIL, ENGINE_JSON and others. You need to do pio build once before using this script. This script only trains and deploys. If pio train or pio deploy fails for some reason, the running engine stays put in most cases. If engine is retrained and deployed successfully, the email sent will have Normal in the title so you can set filtering rules.

mailutils is used in this script. For Ubuntu, you can do sudo update-alternatives --config mailx and see if /usr/bin/mail.mailutils is selected. If you are using a server that blocks email, you will need to use services like SendGrid.

This script does not guarantee no down time since at some point during pio deploy the original engine is shut down. The down time is usually not more than a few seconds though it can be more.

The last thing to do is to add this to your crontab:

0 0 * * *   /path/to/script >/dev/null 2>/dev/null # mute both stdout and stderr to suppress email sent from cron