QuantRocket 1.4 Migration Guide

QuantRocket 1.4 introduces a streamlined procedure for installing and updating the software. For existing QuantRocket users, there is a one-time migration process to align with the new conventions.

What's changed

The Configuration Wizard has gone away and is no longer needed to generate a Docker Compose file. Users can now simply download a ready-to-use Compose file from QuantRocket's website, without the need to configure options or edit the downloaded file. As new versions of QuantRocket become available, users can re-download the latest Compose file and overwrite their existing Compose file.

In addition, environment variables are no longer the preferred way to provide credentials for IB, S3, and other services. QuantRocket's API now supports setting credentials from within JupyterLab using the CLI or Python API. (Environment variables are still used for configuring Houston access for cloud deployments.)

Why the change?

These changes improve the installation process for new users and improve the software update process for existing users.

Previously, the Configuration Wizard prompted users for information such as S3 credentials which the typical new user is not yet ready to think about. Now, users can get started quickly and add credentials later. Also, with the introduction of Sharadar data, QuantRocket now supports use cases that don't require an IB account; therefore entering IB credentials should not be a required installation step.

Software updates are now simplified by eliminating the need for users to manually edit the version numbers in their Compose file and/or re-run the Configuration Wizard. There is now a clean separation between user-provided credentials and configuration (which seldom need to change and which will now be stored outside the Compose file) and the QuantRocket version numbers and service definitions in the Compose file (which change with each update).

Migration Guide

The migration steps, in summary, are as follows:

  1. Follow the new installation guides to install the latest version of QuantRocket.
  2. Use the QuickStart notebook (which is automatically installed with the new installation) to re-enter your license key and IB credentials.
  3. For advanced configurations: re-enter other credentials and custom configurations such as S3 credentials, multiple IB gateways, countdown services, and Papertail integration.

Note: Your data and code will be preserved intact across the migration. Only your credentials must be re-entered.

Step 1: Install new version

First, take down your existing deployment:

$ cd /path/to/quantrocket
$ docker-compose -p quantrocket down

For good measure, make a backup of your existing Compose file, since you can no longer re-generate it from the Configuration Wizard.

$ mv docker-compose.yml docker-compose.yml.BAK

Then, go to the installation page and follow the new installation guide for your platform. Since you already have Docker installed, the steps are minimal and are summarized below:

Local deployments

  • download Compose file
  • run docker-compose up as normal

Cloud deployments

  • download Compose file
  • set HOUSTON_DOMAIN environment variable (renamed from LETSENCRYPT_DOMAIN)
  • run docker-compose up as normal

Step 2: Complete the QuickStart to set license key and IB credentials

Open JupyterLab and use the QuickStart.ipynb notebook to set your license key and IB credentials.

The QuickStart also shows how to clone sample code from QuantRocket's new Codeload Library, which is worth reviewing.

Step 3 for advanced users: Re-enter other credentials and custom configurations

Use the usage guide links below to re-enter your credentials and/or any customized configurations.

Amazon S3 configuration

If you use S3 for database backup/restore, see the API command to enter your S3 credentials.

Multiple IB Gateways

Previously, running multiple IB Gateways involved adding the relevant YAML blocks to docker-compose.yml and setting additional environment variables. Now, the improved procedure is to define the additional IB Gateways in a separate file, docker-compose.override.yml, and set the credentials using the CLI/Python API. The usage guides walks through the process.

Countdown services

The Compose file now includes by default a single countdown service called countdown. (Previously, Compose files only included countdown services if you selected the option in the Configuration Wizard.)

If you're currently using a single countdown service, we recommend using the included countdown service for this purpose (to minimize the number of containers). Suppose your countdown service is currently called countdown-newyork and is set to America/New_York time. Perform the following steps to migrate:

  1. Rename your crontab from quantrocket.countdown-newyork.crontab to quantrocket.countdown.crontab. This will cause it to be seen and loaded by the included countdown service named countdown.
  2. Then, follow the usage guide to set the countdown service timezone to your desired timezone.

If you need to run multiple countdown services, the usage guide shows how.

Timezone of logs

The timezone of your logs, which was previously set in the Configuration Wizard, can now be set via the API.

Papertrail integration

If you previously set up the Papertrail integration in your Compose file, see the usage guide for setting your Papertail host and port via the API.

Satellite service

The Compose file includes by default a single satellite service called satellite. A requirements file is now the preferred way to install packages on the satellite service, rather than environment variables. See the usage guide.

Questions/Problems

If you run into any issues with the migration, post to the community site.