Deploying

Vonage Cloud Runtime allows you to quickly create a running instance on the platform by deploying. Deploying bundles your source code with a configuration file, which creates a package. The package is then uploaded to the platform and becomes a running instance. When you are using a workspace on Code Hub, you can use the terminal to deploy your code once you have finished making changes to a project.

Configuration File

The configuration files gives information to the platform on how to debug and deploy your application. Here is an example configuration file:

project:
    name: app
instance:
    name: dev
    runtime: nodejs22
    region: aws.use1
    application-id: 773c2b45-c20a-4d6b-8afe-24ce29ba6f92
    entrypoint: [node, index.js]
    build-script: "./build.sh"
    capabilities:
        - voice
        - messages-v1
    environment:
        - name: VONAGE_NUMBER
          value: "44700000000"
        - name: INTEGRATION_API_KEY
          secret: MY_SECRET_API_KEY
    secrets:
        - MY_SECRET_API_KEY
debug:
    name: debug
    application-id: 884c2b45-c20a-4d6b-8afe-24ce29ba6f93
    environment:
        - name: DEBUG_VONAGE_NUMBER
          value: "4471111111"
    entrypoint: [nodemon, --inspect, index.js]
    preserve-data: false

• The project name is the unique namespace for your project which can contain many instances.
• The instance name is a unique identifier for your instance.
• region is where the instance will run.
• entrypoint gives the Vonage Cloud Runtime platform information on how to start your application.
• build-script allows you to specify a script to run while the platform builds your application.

You can learn more about the options available to you in the configuration file guide.

Injected Environment Variables

When you deploy your project to Cloud Runtime (or use vcr debug), the platform will inject some environment variables for you along with the environment object from your configuration file.

VCR_PORT
VCR_REGION
VCR_DEBUG
VCR_CODE_DIR
VCR_REGION_ID
VCR_PRIVATE_KEY
VCR_API_REGION_ID
VCR_API_ACCOUNT_ID
VCR_API_ACCOUNT_SECRET
VCR_API_APPLICATION_ID
VCR_INSTANCE_PUBLIC_URL
VCR_INSTANCE_SERVICE_NAME

Application Address and Port

To get your application running on Cloud Runtime correctly, you need to make sure that you are running your application on the correct port. The port differs when using the Cloud Runtime Debugger and when deployed. You can use the VCR_PORT and VCR_HOST environment variables that get injected for you by Cloud Runtime, to ensure you are always using the correct port and host. Here is an example using express.js:

const port = process.env.VCR_PORT;
const host = process.env.VCR_HOST ?? “0.0.0.0”
app.listen(port, host, () => {
 console.log(`App listening on port ${port}`);
});

Some web servers may require the host to be set to 0.0.0.0. Typically, you don't need to configure this manually, as the code manages it automatically.

Health Check Route

The Vonage Cloud Runtime platform expects a route, /_/health, to be available on your application which is used to check the health of your deployed application. The route should not be behind any authentication. Your application will be restarted if this route does not return a 200 status. If the route is missing it will cause your deployment to fail.

Here is an example of the route using express.js:

app.get('/_/health', async (req, res) => {
    res.sendStatus(200);
});

You can use this as an opportunity to perform some checks of your own, and have the platform restart your application for you automatically if it gets into a bad state by returning a non 200 status within 30 seconds.

How to Deploy

You can deploy using the Vonage Cloud Runtime CLI. To deploy, run:

This command does the following:

• Configures your Vonage Application's callbacks as described in your configuration file's capabilities object.
• Packages up the current directory.
• Uploads it to the Cloud Runtime Platform.
• Runs your build script if provided in your configuration file.
• If all successful, runs the command in your entrypoint.

To avoid uploading large or unwanted files as part of your deploy, use a .vcrignore file to exclude them.

By default, the deploy command will look for a configuration file called vcr.yml in the current directory. To use a different configuration file you can run:

For example, to deploy your current code with a configuration file called production.yml you would run:

Deploying with a GitHub Action

If you want to integrate deploying into your GitHub workflow you can add a GitHub Action to deploy for you. The main steps of the Action are to checkout your code, install the Cloud Runtime CLI, then run the deploy command. Here is an example workflow which assumes that you are using a build script to handle the custom aspects of your project:

name: Deploy to Cloud Runtime

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    env:
      VONAGE_API_KEY: ''
      VCR_REGION: 'euw1'
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3.0.2
      - name: Install Cloud Runtime CLI
        uses: Vonage/cloud-runtime-cli@main
      - name: Deploy
        run: |
          vcr deploy --api-key ${{env.VONAGE_API_KEY}} --api-secret ${{ secrets.VONAGE_API_SECRET }} --region aws.${{env.VCR_REGION}} --graphql-endpoint https://graphql.${{env.VCR_REGION}}.runtime.vonage.cloud/v1/graphql

You will need to replace VONAGE_API_KEY and VCR_REGION with your API Key and region you will like to deploy to. This workflow is run manually but you can edit it to run when PRs are closed and so on. You can learn more about GitHub Actions on the Actions Documentation.

Troubleshooting Deployment

You may get a "credentials not found" error if the Vonage Cloud Runtime platform does not have access to your Vonage application's credentials. You can generate a new private key pair using the CLI:

vcr app generate-keys --app-id <app-id> 

View your Deployment

To take a deeper look at your project and deployments you can use the Vonage Cloud Runtime dashboard.

Clicking on your deployed instance will give you access to logs, events, and deployment history. For example, the history tab will show you the deployment history for this instance:

If you deploy more than one instance for your project they will all show on the dashboard:

This is a project named vapi, which has two configuration files. One configuration file has an instance named dev and the other has an instance named prod. This allows you to have multiple instances running the same code but with different environments.

Remove an Instance

If you would like to remove a deployed instance you can use the Vonage Cloud Runtime CLI's instance remove command:

vcr instance remove --project-name <project-name> --instance-name <instance-name> 

So, to remove the dev instance in the above screenshot you would run:

vcr instance remove --project-name vapi --instance-name dev

You can also remove an instance using the instance ID:

vcr instance remove --id <instance-id>

IP Address Allowlist

If you would like to restrict access to your systems, the Vonage Cloud Runtime IP addresses for each region are:

EU West - aws.euw1

• 52.215.68.46
• 46.137.9.43
• 54.72.25.154

US West - aws.use1

• 54.87.47.119
• 3.224.186.73
• 35.153.45.51

APAC Southeast - aws.apse1

• 13.251.207.33
• 52.76.50.31
• 54.169.132.8