Arquivo de configuração

O arquivo de configuração do Vonage Cloud Runtime (vcr.yml), fornece informações à plataforma sobre como depurar e implantar seu aplicativo. Trata-se de um arquivo YAML que contém objetos que permitem configurar onde suas instâncias serão implantadas, a qual aplicação da Vonage você está conectado e assim por diante. Aqui está um exemplo de arquivo de configuração:

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

Projeto

Um projeto é um espaço de nomes para agrupar instâncias.

Nome

name é um identificador único em forma de string para o seu projeto. É possível ter várias instâncias dentro de um projeto, em uma relação de “um projeto para várias instâncias”. Por exemplo, uma instância para executar seu código de produção, uma instância para executar seu código de desenvolvimento e uma instância para o ambiente de teste.

Para ter várias instâncias, crie um novo arquivo de configuração, por exemplo: prod.yml, e certifique-se de que o nome do projeto seja o mesmo. Para implantar arquivos de configuração diferentes, você pode passar os caminhos desses arquivos para o comando da CLI de implantação.

Instância

Uma instância é o seu código em execução na plataforma Vonage Cloud Runtime. Para executar seu código, a plataforma precisa de algumas informações sobre onde e como executá-lo.

Nome

name é um identificador exclusivo, na forma de uma sequência de caracteres, para a sua instância. Isso permite que você as diferencie quando houver várias instâncias no seu projeto. O nome da instância não influencia em qual ambiente ela será executada; isso é controlado pelo region.

Tempo de execução

runtime é a linguagem com a qual você desenvolveu seu código-fonte; as opções disponíveis são:

nodejs18
nodejs22
nodejs24
python3
python3ai
python314
go119
go126
java21
ruby3.3
php8

Região

region é onde a instância será executada. As regiões disponíveis no momento são:

UE - aws.euw1
EUA - aws.use1
APAC (Cingapura) - aws.apse1
APAC (Sydney) - aws.apse2

ID do aplicativo

application-id é o ID do aplicativo da Vonage ao qual a instância será conectada; isso permitirá que o Vonage Cloud Runtime configure os callbacks do aplicativo para você e acesse os números vinculados.

Ponto de entrada

entrypoint é usado para dar instruções ao Vonage Cloud Runtime sobre como executar seu aplicativo. entrypoint recebe uma matriz de strings que é então executada para iniciar seu aplicativo. Por exemplo, para executar meu aplicativo, eu usaria:

node index.js

Isso ficará assim:

entrypoint: [node, index.js]

O primeiro item é o comando a ser executado, seguido por quaisquer opções ou parâmetros.

Script de compilação

build-script permite que você especifique um script para o VCR executar durante a compilação do seu aplicativo. O script de compilação é executado antes do seu entrypoint o comando é executado. Aqui está um exemplo de script de compilação para um projeto em JavaScript e NPM:

#!/bin/bash npm ci --production

Recursos

capabilities para mapear os recursos com o mesmo nome nos Aplicativos da Vonage, as opções disponíveis são:

voice
messages-v1
rtc

Isso permite que o Vonage Cloud Runtime gerencie os webhooks para esses recursos. Para receber os webhooks, você pode usar a função correspondente no SDK do Vonage Cloud Runtime. Consulte a documentação do Voz, Mensagens e Conversa (RTC) prestadores de serviços para obter mais informações.

Meio ambiente

environment permite que você, opcionalmente, passe variáveis de ambiente para o seu aplicativo. O Vonage Cloud Runtime irá inserir as variáveis de ambiente para você quando você executar vcr debug ou quando seu aplicativo for implantado no Vonage Cloud Runtime. Por exemplo, VONAGE_NUMBER o código acima estaria disponível da seguinte forma:

process.env.VONAGE_NUMBER;

O Vonage Cloud Runtime também insere algumas variáveis de ambiente por padrão para você. Isso inclui itens como o ID do aplicativo Vonage e a chave privada. Para obter a lista completa, consulte o guia de implantação.

Segredos

Você pode expor à instância os segredos que já criou por meio da CLI de duas maneiras.

Usando o secrets lista — o segredo é exposto diretamente como uma variável de ambiente usando seu próprio nome:

instance:
    secrets:
        - MY_API_KEY
        - DATABASE_PASSWORD

MY_API_KEY ficaria então disponível como process.env.MY_API_KEY.

Usando o environment objeto — o segredo é associado a um nome de variável específico:

instance:
    environment:
        - name: API_KEY
          secret: MY_API_KEY

API_KEY ficaria então disponível como process.env.API_KEY.

Para obter mais informações sobre como criar e gerenciar segredos, consulte o Guia sobre segredos do Vonage Cloud Runtime.

Percurso de avaliação de saúde

health-check-path permite que você personalize o caminho usado pela plataforma para verificar o estado de funcionamento da sua instância. O caminho padrão é /_/health. O endpoint deve retornar um status HTTP 200.

instance:
    health-check-path: /_/health

Para obter mais informações sobre a exigência de exame médico, consulte o guia de implantação.

Segurança

security permite que você controle o acesso aos endpoints do seu aplicativo. Por padrão, todos os endpoints são acessíveis publicamente. Você pode definir um nível de acesso padrão e adicionar substituições específicas para cada caminho.

instance:
    security:
        access: private
        override:
            - path: "/webhooks/*"
              access: public
            - path: "/api/**"
              access: authenticated
              auth-method: vonage_basic

Os níveis de acesso disponíveis são:

public — não é necessária autenticação
private — não acessível de fora da plataforma
authenticated — requer autenticação por meio de auth-method

O único compatível auth-method é vonage_basic.

Os padrões de caminho aceitam dois caracteres curinga:

* — corresponde a um único segmento de caminho (por exemplo, /users/*/profile)
** — corresponde a vários segmentos de caminho (por exemplo, /api/**)

Observação: os callbacks de webhook da Vonage devem ser configurados para public para que a plataforma da Vonage possa entrar em contato com eles.

Escalonamento

scaling permite que você controle o número mínimo e máximo de réplicas que a plataforma executará para a sua instância.

instance:
    scaling:
        min-scale: 1
        max-scale: 5

Cenário min-scale para 1 ou superior mantém pelo menos uma réplica em execução o tempo todo, evitando inicializações a frio. O valor mínimo padrão é 0 (ajuste para zero quando estiver inativo).

Domínios

domains permite que você configure um ou mais nomes de domínio personalizados para sua instância. Antes de adicionar um domínio, crie um registro CNAME no DNS apontando para custom.[region].runtime.vonage.cloud.

instance:
    domains:
        - api.myapp.example.com

Depuração

O objeto de depuração fornece informações à CLI do Vonage Cloud Runtime sobre como executar seu aplicativo no modo de depuração. Para obter mais informações sobre depuração, consulte o Guia de depuração do Vonage Cloud Runtime.

Nome

name permite que você atribua um nome ao seu depurador, de modo que a URL de depuração gerada seja estática, em vez de aleatória, quando o depurador for iniciado.

ID do aplicativo

Isso permite que você especifique um ID de aplicativo da Vonage diferente do da sua instância.

Meio ambiente

environment na seção de depuração funciona da mesma forma que ambiente da instância, mas só se aplica quando o programa está em execução vcr debug. Isso permite que você utilize diferentes variáveis de ambiente localmente, sem afetar sua instância implantada.

debug:
    environment:
        - name: LOG_LEVEL
          value: "debug"
        - name: API_KEY
          secret: DEV_API_KEY

Ponto de entrada

entrypoint para depuração, funciona da mesma forma que o ponto de entrada da instância. Isso oferece a flexibilidade de ter um fluxo de trabalho de depuração separado, incluindo, por exemplo, um monitor de arquivos para reiniciar o aplicativo quando forem feitas alterações:

nodemon --inspect index.js

Fica assim:

entrypoint: [nodemon, --inspect, index.js]

Preservar dados

preserve-data permite que você mantenha os dados armazenados com Estado da instância entre as execuções do depurador. O valor padrão é falso.