Skip to content

OpenVidu Elastic installation: Oracle Cloud Infrastructure#

Oracle Cloud Infrastructure

Info

OpenVidu Elastic is part of OpenVidu PRO. Before deploying, you need to create an OpenVidu account to get your license key. There's a 15-day free trial waiting for you!

This section describes how to deploy a production-ready OpenVidu Elastic instance on Oracle Cloud Infrastructure (OCI). The deployed services are identical to those in the On Premises Elastic installation, but are provisioned as OCI resources and the process is fully automated using the Terraform CLI.

  • OCI Object Storage (S3-compatible via Customer Secret Keys) is used for storing application data and recordings.
  • OCI Vault is used to securely store deployment secrets.
  • Media Node scale-out is handled automatically by the OCI Instance Pool autoscaling configuration based on system load, and scale-in is delegated to an OCI Function that performs a graceful drain before terminating the instance. You can also use a fixed number of Media Nodes.

Prerequisites#

  • An Oracle Cloud Infrastructure account with permissions to create Compute instances, VCNs, Object Storage buckets, Vaults, Functions and IAM resources.
  • Terraform CLI installed on your machine.
  • Git installed on your machine.

The deployment architecture is as follows:

OpenVidu Elastic Oracle Cloud Infrastructure Architecture
OpenVidu Elastic Oracle Cloud Infrastructure Architecture

  • The Master Node acts as a Load Balancer, managing traffic and distributing it among the Media Nodes and the services running on the Master Node itself.
  • The Master Node has its own Caddy server acting as a Layer 4 (for TURN with TLS and RTMPS) and Layer 7 (for OpenVidu Dashboard, OpenVidu Meet, etc., APIs) reverse proxy.
  • WebRTC traffic (SRTP/SCTP/STUN/TURN) is routed directly to the Media Nodes.
  • Scale-out is performed automatically by the OCI Instance Pool autoscaling configuration based on the average CPU of the pool. Scale-in is delegated to an OCI Function that gracefully drains the target Media Node before terminating it.

Custom scale-in strategy#

Scale-out is handled natively by the OCI Instance Pool autoscaling configuration, which adds Media Nodes when the pool's average CPU exceeds scaleTargetCPU. Scale-in, however, uses a custom strategy to enable the graceful shutdown of Media Nodes, ensuring that active Rooms are never disrupted when the cluster removes a Media Node.

  • An OCI Function is deployed and triggered on a regular schedule. It polls the average CPU of the Instance Pool against scaleTargetCPU and never scales the pool below minNumberOfMediaNodes, and when a scale-in decision is made, the target Media Node is flagged as "draining" so it stops accepting new Rooms.
  • Each Media Node runs a systemd daemon that periodically checks whether the instance has been marked as "draining". If so, the graceful shutdown script is triggered, which waits for all active Rooms on that node to end before shutting the instance down.

Using your own scale-in function image#

By default, the OCI Function pulls the scale-in image published by OpenVidu in the Madrid OCIR (mad.ocir.io). If you prefer to host the image in your own OCI Registry — for example, to avoid cross-region pulls, comply with internal policies, or pin a customised build — you can build and push it yourself, then point the scale_in_function_image variable to your image.

  1. From the cloned openvidu-oracle repository, navigate to the scale-in function source directory:

    cd openvidu-oracle/pro/scalein-function

  2. Authenticate Docker against your OCI Registry. You will need an OCI Auth Token for the user you log in with:

    docker login <region-key>.ocir.io -u '<tenancy-namespace>/<username>' -p '<auth-token>'

    Replace <region-key> with the OCIR region code (for example fra for Frankfurt, iad for Ashburn, mad for Madrid).

    Replace <username> with the value matching your authentication setup — the exact format depends on whether your tenancy uses identity domains, federation with IDCS, or local IAM users. See Pushing Images Using the Docker CLI for the exact pattern in each case (typical forms are <username>, <identity-domain>/<username>, or oracleidentitycloudservice/<email>).

  3. Build and tag the image. The tag must follow the format <region-key>.ocir.io/<tenancy-namespace>/<repo>:<tag>:

    docker build -t <region-key>.ocir.io/<tenancy-namespace>/scale-in-function:<tag> .

  4. Push the image to OCIR:

    docker push <region-key>.ocir.io/<tenancy-namespace>/scale-in-function:<tag>

  5. Update terraform.tfvars with the new image reference:

    scale_in_function_image = "<region-key>.ocir.io/<tenancy-namespace>/scale-in-function:<tag>"

Info

Make sure the OCI Function's compartment has the IAM policies needed to pull from the target repository. If the repository lives in a different tenancy from the OCI Function, see Pulling Images from Repositories in other Tenancies for the required Endorse/Admit/Define policy statements.

Deployment details#

  1. Clone the OpenVidu repository containing the Terraform files:

    git clone https://github.com/OpenVidu/openvidu-oracle.git
git -C openvidu-oracle checkout 3.7.0
cd openvidu-oracle/pro/elastic

  2. Copy terraform.tfvars.example to terraform.tfvars, update the required parameters with your values, and adjust any optional defaults as needed.

    Information about parameters

    Mandatory Parameters

    Input Value Description
    tenancy_ocid OCI Tenancy OCID. Required for the Object Storage namespace.
    compartment_ocid OCI Compartment OCID where resources will be created.
    user_ocid OCI User OCID used to create Customer Secret Keys for S3-compatible access to Object Storage.
    stackName Stack name for the OpenVidu deployment.
    openviduLicense OpenVidu PRO license key. Visit https://openvidu.io/account to obtain your license.

    Optional Parameters

    Input Value Default Value Description
    region "eu-frankfurt-1" OCI region where resources will be created.
    availability_domain 1 Availability Domain number (1, 2, or 3) to use for resources.
    masterNodeShape "VM.Standard.E4.Flex" OCI Compute shape for the OpenVidu Master Node.
    masterNodeOcpus 2 Number of OCPUs for the Master Node (applies to Flex shapes only).
    masterNodeMemory 8 Memory in GB for the Master Node (applies to Flex shapes only).
    masterNodeDiskSize 100 Boot disk size in GB for the Master Node.
    mediaNodeShape "VM.Standard.E4.Flex" OCI Compute shape for the OpenVidu Media Nodes.
    mediaNodeOcpus 3 Number of OCPUs for each Media Node (applies to Flex shapes only).
    mediaNodeMemory 4 Memory in GB for each Media Node (applies to Flex shapes only).
    mediaNodeDiskSize 100 Boot disk size in GB for the Media Nodes.
    fixedNumberOfMediaNodes 0 If > 0, deploys a fixed number of Media Nodes with no autoscaling and no scale-in OCI Function (initialNumberOfMediaNodes, minNumberOfMediaNodes, maxNumberOfMediaNodes, scaleTargetCPU and scale_in_function_image are ignored). If 0 (default), the deployment is elastic and autoscaling is enabled.
    initialNumberOfMediaNodes 1 Initial number of Media Nodes to deploy. Ignored when fixedNumberOfMediaNodes > 0.
    minNumberOfMediaNodes 1 Minimum number of Media Nodes the autoscaling Instance Pool will keep running. Ignored when fixedNumberOfMediaNodes > 0.
    maxNumberOfMediaNodes 5 Maximum number of Media Nodes the autoscaling Instance Pool can launch. Ignored when fixedNumberOfMediaNodes > 0.
    scaleTargetCPU 50 Target CPU percentage. The Instance Pool autoscaling triggers scale-out above this threshold; the OCI Function triggers graceful scale-in when usage falls below it. Ignored when fixedNumberOfMediaNodes > 0.
    scale_in_function_image mad.ocir.io/axp2ice0s7el/openvidu-scalein:main OCIR image URL consumed by the OCI Function that handles graceful Media Node scale-in. Defaults to the image published by OpenVidu in the Madrid OCIR. See Using your own scale-in function image if you want to host it in your own registry. Ignored when fixedNumberOfMediaNodes > 0.
    certificateType "letsencrypt" Certificate type for the OpenVidu deployment. Options:
    • selfsigned - Not recommended for production use. Intended for testing or development environments only. A FQDN is not required.
    • owncert - Suitable for production environments. Uses your own certificate. A FQDN is required.
    • letsencrypt - Suitable for production environments. Can be used with or without a FQDN (if no FQDN is provided, a random sslip.io domain will be used).

    Warning: sslip.io is currently experiencing Let's Encrypt rate limiting issues, which may prevent SSL certificates from being issued. It is recommended to use your own domain name. Check this community thread for troubleshooting and updates.
    domainName (none) Domain name for the OpenVidu deployment. Optional — if not provided, a sslip.io domain will be used instead.
    ownPublicCertificate (none) If the certificate type is owncert, this parameter specifies the public certificate in base64 format.
    ownPrivateCertificate (none) If the certificate type is owncert, this parameter specifies the private certificate in base64 format.
    initialMeetAdminPassword (none) Initial password for the admin user in OpenVidu Meet. Alphanumeric characters, underscores or hyphens only (A-Z, a-z, 0-9, _, -). If not provided, a random password will be generated.
    initialMeetApiKey (none) Initial API key for OpenVidu Meet. Alphanumeric characters, underscores or hyphens only (A-Z, a-z, 0-9, _, -). If not provided, no API key will be set; one can be configured later from the Meet Console.
    bucketName (none) Name of the OCI Object Storage bucket for application data and recordings. If left empty, a bucket will be created with a default name.
    rtcEngine "pion" WebRTC media engine to use. Options:
    • pion - Default media engine.
    • mediasoup - Alternative media engine with different performance characteristics.
    vault_ocid (none) OCI KMS Vault OCID for secrets management. If left empty, a new vault will be created.
    key_ocid (none) OCI KMS Key OCID for secrets management. If left empty, a new key will be created.
    additionalInstallFlags (none) Additional optional flags to pass to the OpenVidu installer (comma-separated, e.g., --flag1=value, --flag2).

  3. Deploy with Terraform using the following commands:

    terraform init
terraform apply

  4. Logs will appear in the terraform apply console output. Wait for it to finish and display Apply Complete!. Then go to OCI Object Storage and wait for the SSH key to appear in your configured bucket.

    Warning

    After downloading the SSH key, it is strongly recommended to DELETE IT from the bucket. This file is the private key used to access the Master Node — if exposed, unauthorized users could gain access.

    SSH Key in bucket

  5. Set the correct permissions on the SSH key so it can be used.

    chmod 600 <PATH_TO_THE_KEY>/openvidu_private_ssh_key_<STACK_NAME>.pem

    $KeyPath = "<PATH_TO_THE_KEY>" &&
icacls $KeyPath /inheritance:r &&
icacls $KeyPath /grant:r "$($env:USERNAME):(R)"

Access OpenVidu#

To verify that your OpenVidu deployment is working correctly, check the credentials in the OCI Vault Secrets Manager.

  1. Navigate to the OCI Secrets Manager in the OCI Console.
  2. Click the secret you want to view.

  3. Scroll down to "Versions", click the "3 dots" menu next to the current version, and select "View secret contents".

    View Secret

    Warning

    Click "Show decoded Base64 digit" to see the actual value of the secret.

SSH into the Master Node by running the following command from the directory where your SSH key is located: 

ssh -i openvidu_private_ssh_key_<STACK_NAME>.pem ubuntu@PUBLIC_INSTANCE_IP

Then navigate to /opt/openvidu/config/ where you will find all credentials in the following files:

  • openvidu.env
  • meet.env

Open OPENVIDU_URL and you will see the OpenVidu Meet interface.

Log in with MEET_INITIAL_ADMIN_PASSWORD to start using OpenVidu Meet.

Configure your application to use the deployment#

To configure your OpenVidu application, you will need your OCI credentials. You can retrieve them by following the steps in View OpenVidu credentials in the Web or View OpenVidu credentials in the instance.

Your authentication credentials and the URL to point your applications to are:

OpenVidu Meet:

  • OPENVIDU_URL: The URL used to access OpenVidu Meet, always https://yourdomain.example.io/.
  • MEET_INITIAL_ADMIN_USER: The user account for accessing the OpenVidu Meet Console. Always admin.
  • MEET_INITIAL_ADMIN_PASSWORD: The password for accessing the OpenVidu Meet Console.
  • MEET_INITIAL_API_KEY: The API key for using the OpenVidu Meet Embedded and OpenVidu Meet REST API.

Note

MEET_INITIAL_ADMIN_USER, MEET_INITIAL_ADMIN_PASSWORD, and MEET_INITIAL_API_KEY are initial settings only. Changing them here will not affect the deployment — they can only be modified from the Meet Console.

OpenVidu Platform:

  • LIVEKIT_URL: The URL used with LiveKit SDKs. This can be either wss://yourdomain.example.io/ or https://yourdomain.example.io/, depending on the client library you are using.
  • LIVEKIT_API_KEY: The API key for LiveKit SDKs.
  • LIVEKIT_API_SECRET: The API secret for LiveKit SDKs.

Troubleshooting initial Oracle Cloud Infrastructure deployment#

If something goes wrong during the initial Oracle Cloud Infrastructure deployment, you will not be able to reach the OPENVIDU_URL. This can happen due to a misconfiguration in the parameters, insufficient permissions, or a problem with OCI services. The steps below will help you troubleshoot the issue and identify the root cause:

  1. Check whether the instance is running. If it is not, review the output of the terraform apply command for any errors.

  2. If the instance is running, SSH into it and inspect the logs by running the following command:

    cat /var/log/cloud-init-output.log

    These logs contain detailed information about the Oracle Cloud Infrastructure deployment process.

  3. If everything appears to be in order, check the status and logs of the installed OpenVidu services on the Master Node and Media Nodes.

Configuration and administration#

Once OPENVIDU_URL is reachable, the deployment is complete and working. See the Administration section to learn how to manage your OpenVidu Elastic deployment.