Deploying calculations

Nexus can run your calculation in the cloud and have it triggered on fixed intervals (for example every hour, or every day at 24:00) or simply whenever its input data is changed. To make this happen, you need to deploy your calculation.

Your calculation may be used by different customers and run with slightly different calibration parameters for each customer (of course this is something you need to give permission for). For each customer, input data will be in the same standardized format and data types to ensure that your code can stay the same.

Warning

When running your calculation in the cloud, Nexus provisions 5GB of working memory. Make sure your calculation does not exceed this amount.

Register your calculation¶

The first step in making your calculation operational in the cloud is to register it. Nexus needs to know the name of your calculation in order to run it. Therefore, register your calculation by emailing the name of your calculation to . StellaSpark will confirm successful registration by confirmation email within 48 hours. In the meantime, you may proceed with the next step: preparing your calculation for deployment.

Preparing for deployment¶

To make your calculation operational on the Nexus server, you have to adhere to four golden rules.

1. Command line interface¶

Nexus triggers your calculation through the command line. If your calculation has any calibration parameters or settings that are potentially different each run and that you want to provide as input, you pass them to your code as command line arguments.

2. Input from Nexus, output to Nexus¶

Your calculation pulls its input data from the Nexus Database/Datastore, and outputs calculation results back to Nexus Database/Datastore. At runtime, Nexus passes input_schema and output_schema as command line arguments. The calculation should use these arguments to pull input data from the correct schema and write its output to the right schema. As such the input_schema and output_schema must be dynamic everywhere in your calculation.

Variable Meaning

input_schema Database schema name (world) that your calculation code uses as input for a particular run. For testing, this is often the 'sandbox' world. If you are developing the calculation for a particular client organization, this variable will contain the name of the world of this organization. In the 'live' server environment, the input_schema can be different each run, depending on the worlds that use the calculation.

output_schema Database schema name that your calculation writes its output results to. Write your intermediate tables and output tables to this (temporary) schema. In the 'live' server environment, the output_schema can be different each run. Nexus will pickup the results from there and integrate them back into the world.

Nexus injects environment variables on runtime that provide the correct login credentials for Nexus Database and Datastore. Your calculation should use the injected credentials to ensure that your calculation has the correct authorizations when running operationally on the server. If you use the example calculation, there is no need to worry about this, since the config file already fetches all environment variables for you.

Variable	Meaning
`SERVER`	A true/false variable that indicates whether calculation runs live on the server or not (only used for correctly fetching Database and Datastore credentials)
`DB_USER`	Nexus Database username
`DB_PASSWORD`	Nexus Database password
`DB_HOST`	Nexus Database hostname
`DB_NAME`	Nexus Database name
`ACCESS_KEY_ID`	Nexus Datastore access key ID
`SECRET_ACCESS_KEY`	Nexus Datastore secret access key
`SESSION_TOKEN`	Nexus Datastore session token

4. Packaging with Docker¶

On your own computer, your calculation runs straight from your code editor or from your own command line. However, to run the calculation 'live' in Nexus, you need to package it in a Docker container and then upload the container image to Nexus. Packaging with Docker means that you encapsulate your code into a so-called Docker container. The main reason we use Docker is that if your calculation runs successfully (using Docker) on your machine, then it will also run successfully in Nexus.

Note

Don't have Docker yet? Get Docker Desktop for your platform from www.docker.com/products/docker-desktop

Add a so-called Dockerfile (which is, by convention, always literally called 'Dockerfile') to the main folder where your calculation code resides. This file should not contain a file extension. The Dockerfile describes the environment that your code will be run in. To make things easier, we already provided template Dockerfiles for common programming languages as part of the Demo Interpolation and Demo Precipitation Deficit. If you're not using the demo as starting point, you can create your own Dockerfile.

How to run your calculation on your machine using Docker?

Download the build script here
Put the build script in the root of your code directory and run it with a shell or command prompt:
```
build {name_of_your_calculation}
```

Start your calculation (we use a Python example here) with all arguments including input_schema and output_schema:

docker run -it {name_of_your_calculation} python main.py --input_schema={your_input_schema} --output_schema={your_output_schema} --other_argument={can_be_anything}

Deployment¶

Deploy your calculation to Nexus with the Deployment script.

Download the deployment script here
Put the deployment script in the root of your code directory and run it with a shell or command prompt:
```
deploy {name_of_your_calculation} {web_api_token}
```
The deployment script will start building your Docker container and upload the container image to Nexus.