The free VM build executor is available in the VB Studio's built-in free account and runs on VB Studio's default VCN.

The more VM executors you have available, the more builds your organization's members can run at the same time. As the built-in free account offers only one VM executor, your VB Studio organization members can run only one build at a time. If members trigger multiple builds while a build is already running, they must wait until the build running on the VM executor is complete. The VM executor then runs the queued builds on a first-come-first served basis.

The free VM build executor template, called System Default OL7 for Visual Builder, includes the necessary software to run extension and visual application builds. You can't change the default executor template's configuration. This table lists the software defined in System Default OL7 for Visual Builder:

If you want to add more executor templates to reduce the wait time for your organization's members, to create custom executor templates with different software configurations, or to use advanced features (such as using your own VCN or using a different VM shape), you should configure VB Studio to connect to your own OCI account.

In a VB Studio visual application project, you use build jobs to compile the source code, package the visual application, and deploy it to a Visual Builder instance. The builds and pipelines run on build executors, also called VM build executors. These VM executors are Oracle Cloud Infrastructure (OCI) VM Compute instances dedicated to run VB Studio builds.

In some Oracle Cloud regions and data centers, VB Studio is available pre-configured with a built-in free account, which provides one free VM executor that you can use to run build jobs that package and deploy your extensions. However, there some limitations (see VB Studio's Free VM Build Executor) associated with the free VM build executor, so you may want to connect to your own OCI account instead, if you have one. See OCI Resources in VB Studio for more a more comprehensive comparison between the built-in free account, free tier account, and your OCI account.

To find out whether your VB Studio instance is connected to the built-in free account, follow these steps:

1. In the navigation menu, click Organization .
2. Click the OCI Account tab.

   You should see a similar page:

   
   

   
   

   
   

Depending on your VB Studio's data center, you may or may not see the Built-in (Free) option.

Before you create a project, note that in a VB Studio instance that has no projects and no VM executors, the first VM executor is created for you when you create the first project. If the project isn’t the initial one, the VM executor must be created manually.

You can create and manage build executor templates from the Organization Administration page's Virtual Machine Templates tab.

A VM executor can run one build at a time. When you add a VM build executor, you allocate an OCI VM Compute instance to run VB Studio builds. If you expect your organization's members to run builds in parallel jobs that refer to a common executor template, you should add multiple VM executors for that executor template. Note that the more VM executors you have running at a specific time, the higher the cost. To minimize the higher cost, use the Sleep Timeout setting to automatically shut down inactive VM executors.

Note

You can't add or manage VM executors if VB Studio is connected to the built-in free account. If you want to add more than one VM executor, configure VB Studio to connect to your OCI account.

Here's an example of multiple VM executors that use a common executor template.

You add and manage VM executors from the Build Executors tab on the Organization page:

1. In the navigation menu, click Organization
2. Click the Build Executors tab.

This table describes the actions you can perform to manage VM executors.

Action	How To
Add the free VM build executor in the built-in free account	You can add and use the free VM build executor only if your VB Studio instance is connected to the built-in free account. The free VM build executor will be automatically created upon creation of the first project in the org. You can also add it by clicking Create Free VM Build Executor on the Build Executors tab. VB Studio creates the free VM build executor that uses the System Default OL7 for Visual Builder template. You can't change the VM executor's template. The new VM executor is in the Pending state until you manually start it or trigger a job's build that references the associated executor template.
Find VM executors of an executor template	In the search box, enter the executor template's name.
Sort VM executors	Click the arrow icon in the column's header to sort VM executors. For example, to sort VM executors by their state, click the arrow icon in the Status column's header.
Add a VM executor in the VB Studio's default VCN	Find VM executors of the executor template you want to use. If there are no VM executors of the executor template, jump to the next step. If you find one or more VM executors that use the executor template, get each VM executor's VCN name. If the VCN's name isn't vbs-executor-vcn, click and select Delete to delete the VM executor. You should not add VM executors to different VCNs that use the same executor template. Click + Create VM. In the Add VM Build Executor dialog box, in Quantity, specify the number of VM executors you want to create. To minimize build execution delays, set the number to the number of jobs that you expect to run in parallel using the template you'll specify in Build Executor Template. If you're not sure, start with one VM executor. You can add more VM executors later, based on your actual usage. In Build Executor Template, select the executor template. In Region, select the region that's closer to you geographically. The drop-down list displays regions your OCI account is subscribed to. In Shape, select the VM executor's shape. For example: Wait for a few seconds and then scroll down the page. Here's an example of what you might see. VB Studio calculates the number of Compute VM instances that can be created using shape you selected and displays it in the dialog, below the Reserved Public IP (Optional) selector. Below that, there's a line shows the realtime statistics that were used to make this calculation, using your settings. As you change your settings, new statistics are displayed. See What Determines How Many VMs I Can Create? for more information about how the calculations are made. If the required number of Compute VM instances aren't available, choose another shape. Select the Reserved Public IP that you want to add to the VM executor. You can add one Reserved Public IP to each VM executor. An allow listing for your VM executor is possible only if you specify an OCI account by assigning a Reserved Public IP to a build executor. The Reserved Public IP must be defined in the compartment of the specified OCI account. In VCN Selection, select Default. Click Add. The new VM executor is in the Pending state until you manually start it or trigger a job's build that references the associated executor template.
Add a VM executor in another compartment's VCN	Before you add a VM executor, make sure you've added a public subnet in the VCN. See Create and Configure a Public Subnet in a VCN. Find VM executors of the executor template you want to use. If there are no VM executors of the executor template, jump to the next step. If you find one or more VM executors that use the executor template, get each VM executor's VCN name. If the VCN's name is different from your VCN, click and select Delete to delete the VM executor. You should not add VM executors to different VCNs that use the same executor template. Click + Create VM. In the Add VM Build Executor dialog box, in Quantity, specify the number of VM executors you want to allocate. In Build Executor Template, select the executor template. In Region, specify the VM executor's region. In Shape, select the VM executor's shape. For example: Wait for a few seconds and then scroll down the page. Here's an example of what you might see. VB Studio calculates the number of Compute VM instances that can be created using shape you selected and displays it in the dialog, below the Reserved Public IP (Optional) selector. Below that, there's a line shows the realtime statistics that were used to make this calculation, using your settings. As you change your settings, new statistics are displayed. See What Determines How Many VMs I Can Create? for more information about how the calculations are made. If the required number of Compute VM instances aren't available, choose another shape. Select the Reserved Public IP that you want to add to the VM executor. You can add one Reserved Public IP to each VM executor. An allow listing for your VM executor is possible only if you specify an OCI account by assigning a Reserved Public IP to a build executor. The Reserved Public IP must be defined in the compartment of the specified OCI account. In VCN Selection, select Custom. In VCN Compartment, select the compartment. If you're an Oracle Cloud OS Management Service (OSMS) user, don't select the OSMS compartment or a compartment with an OSMS policy. In VCN, select the VCN. In Subnets Compartments, select the compartments where your public subnets are. By default, it adds your VCN's compartment. If required, you can add more compartments. In Subnets, select a subnet. The list shows public subnets only. You can add multiple public subnets. If VB Studio can't create a VM executor on the first subnet you've added, it tries to create it on the second subnet, and so on. Click Validate Network Setup. After successful validation, click Add. The new VM executor is in the Pending state until you manually start it or trigger a job's build that references the associated executor template.
Get the name and IP addresses of a VM executor's VCN subnet.	In the VM executor's Details column, click Show machine details. Note the VCN subnet's name. The VM executor's subnet name is displayed only if it's in the Available state. If the VM executor is in the Stopped or the Pending state, click and select Start to start the VM executor.
View a VM executor’s log	The VM executor’s log has entries for all events along with information about when the events occurred, the type of event, and event details. Select the VM executor, click Actions and select Display Log. In the Provisioning Log window, review the log. To download the log file to your computer, click Download Log.
Start or stop a VM executor manually	When a build of a job triggers, its VM executor starts automatically if it was in the stopped state. It takes some time to start a VM executor, and the user must wait for a VM executor to start before the job's build runs on it. Similarly, a VM executor stops automatically if no builds run on it during the sleep timeout period. At times, you may want to manually start a VM executor before triggering a job's build or stop it to free resources immediately. To start or stop a VM executor, click Actions and select Start or Stop. To start or stop multiple VM executors, select their check boxes, click Update Selected and select Start selected VMs or Stop selected VMs.
Delete a VM executor	To delete a VM executor, click Actions and select Delete. If the Delete action doesn't delete the VM executor, you can force a delete using the Force Delete action. To delete multiple VM executors, select their check boxes, click Update Selected and select Delete selected VMs.
Change the sleep timeout of all VM executors	Set the sleepout time to stop inactive VM executors automatically. By default, it is 30 minutes. The higher the sleep timeout value, higher will be your cost as inactive VM executors continue to be in the Available state for a longer time. If you don't expect your organization's users to run builds frequently, specify a lower sleep timeout. When a VM executor starts from the Stopped state, it installs the operating system and all software packages of the executor template. This takes time and your organization's users must wait for the build to start until the VM executor is in the Available state. If you expect your organization's users to run builds frequently, specify a higher sleep timeout value. Click Sleep Timeout. In the Sleep Timeout dialog box, change the timeout duration to define how long should a VM executor be in the Available state if no builds run on it. Click Save.
Reset the VM executor	Use the Try to Reset action if the build executor is stuck in the Error Recoverable status. The Try to Reset action will try to remove all used OCI resources of the VM executor. To reset a VM executor, click Actions and select Try to reset.

You may want to configure VB Studio to connect to your own OCI account if you need more VM build executors to reduce the wait time for your organization's members, you want to create custom build executor templates, or you want to use advanced features for VM executors (such as use your own VCN or use a different VM shape).

1. Click the VM Build Executors tab.
2. Click + Create VM.
3. In the Add VM Build Executor dialog box, in Quantity, specify the number of VM executors you want to allocate.

   To minimize build execution delays, set the number of VM executors to the number of jobs that you expect to run in parallel using that template. If the OCI VM quota is available, that number of VM executors will be added to the Virtual Machines tab.

   If you're not sure about the number of VM executors you'll need, start with one VM executor and then add more as required. Note that the more VM executors you have running at a specific time, the higher the cost of OCPUs. To minimize the higher cost, use the Sleep Timeout setting on the VM Build Executors tab to automatically shut down inactive VM executors. You can always return to the VM Build Executors tab to remove or add VM executors, based on your actual usage.

4. In Build Executor Template, select System Default OL7 for Visual Builder or a executor template with Node.js 16 (or higher) software.
5. In Region, Shape, and VCN Selection specify the VM's region, shape, and Virtual Cloud Network (VCN).
   • A region is a localized geographic area where the data centers are located. Remember, a VM executor is a VM on OCI Compute. Choose the region where your VB Studio account is or the one that's closest to you geographically.
   • A shape is a template that determines the number of CPUs, amount of memory, and other resources allocated to the created instance. Choose a shape of your preference.
   • A VCN is a software-defined network that you set up in the Oracle Cloud Infrastructure data centers in a particular region. By default, builds run in your VB Studio's compartment. To run builds in your own VCN, select Custom and specify its details.

   To learn more about regions and shapes, see Regions and Availability Domains and Compute Shapes. To find more about VCNs, see VCNs and Subnets.

6. Click Add.

A Virtual Cloud Network (VCN) is a software-defined network that you set up in the OCI data centers of a region. A subnet is a subdivision of a VCN. A VM build executor always runs in a VCN's public subnet.

You can choose to run a VM executor in the VB Studio compartment's VCN or in another compartment's VCN. Run the VM executor in the VB Studio compartment's VCN if you don't have a VCN or want to use the default option without any additional configuration. Run the VM executor in another compartment's VCN if you want the VM executor to access Oracle Cloud services running in that compartment's VCN.

VB Studio provides various software packages in the build executors' software catalog. Some software packages are available by default in each executor template.

If you haven't configured VB Studio to add VM executors, you can add your first Docker deployment VM from the Organization page's Build Executors tab.

1. Configure VB Studio to connect to your OCI account.
2. In the navigation menu, click Organization .
3. Click the Build Executors tab.
4. In the Custom Docker Executor tile, click Create Docker Executor.
   
   
   
   
   
5. Add details to the Add VMs for Creating Docker Executors dialog:
   1. Number of VMs: Specify the number of Docker deployment VMs you want to create.
      The number you specify doesn't include the Docker Management VM. For example, if you specify 4 in Number of VMs, VB Studio will create five VMs: four Docker deployment VMs and one Docker Management VM.
   2. Executors created per VM: Enter the maximum number of Docker executors you want to deploy in each Docker deployment VM.
   3. Region: Select the region that's closer to you geographically.
      The drop-down list displays regions your OCI account is subscribed to.
   4. Shape: Select the Docker executor's shape.

      As this is your first Docker deployment VM, the Docker Management VM is also created with the same shape. Choose a shape with at least two OCPUs and 16 GB of RAM.

      After selecting the shape, wait for a few seconds. VB Studio calculates the number of Compute VM instances that can be created with the selected shape and displays it in the dialog box. If the required number of Compute VM instances aren't available, choose another shape.
   5. Volume: Specify the storage capacity for each Docker deployment VM.
   6. Number of OCPUs: If you've selected a Flex shape, specify the number of OCPUs to add in each Docker deployment VM.
   7. Amount of Memory: If you've selected a Flex shape, specify each Docker deployment VM's memory.
   8. Use only for project(s): (Optional) Select one or more projects to assign to this Docker deployment VM. After the Docker deployment VM is created, it will be restricted to running builds for the assigned projects. Builds for these projects will only run on this VM, and builds from other projects won't run on this VM.
6. For VCN Select, choose Default or Custom.
   • If you chose Default, click Create. You are finished with this task.
   • If you chose Custom, continue to the next step.
7. Fill out the additional details for the custom VCN:
   1. VCN Compartment: Select the compartment.
      If you're an Oracle Cloud OS Management Service (OSMS) user, don't select the OSMS compartment or a compartment with an OSMS policy.
   2. VCN: Select the VCN.
   3. Subnets Compartments: Select the compartments where your public subnets are. By default, it adds your VCN's compartment. If required, you can add more compartments.
   4. Subnets: Select a subnet. The list shows public subnets only.
      You can add multiple public subnets. If VB Studio can't create a Docker executor on the first subnet you've added, it tries to create it on the second subnet, and so on.
8. Click Validate Network Setup.
9. Click Create.

If you've created one or more VM executors and want to use Docker executors to run builds, you can migrate those VM executors to Docker.

1. If you're using the free VM build executor or are connected to the OCI free tier account, configure VB Studio to connect to your OCI account.
2. In the navigation menu, click Organization .
3. Click the Build Executors tab.
4. Capture details for your current VM executors in case you want to revert back from Docker executors to VM executors.
   1. To capture ID, template, and shape information, copy the contents of the Build Executors table and paste to a text file.
   2. To capture the contents of the Details column, click Show machine details for each VM executor, copy the VM Build Executor Configuration details, and paste to a text file.
5. Click Migrate to Docker.
6. In the Do you want us to re-create your VM executors as Docker images dialog, enter the required details.
   1. In Number of VMs, specify the number of Docker deployment VMs you want to create.
      The number you specify doesn't include the Docker Management VM. For example, if you specify 4 in Number of VMs, VB Studio will create five VMs: four Docker deployment VMs and one Docker Management VM.
   2. In Executors created per VM, enter the number of Docker executors you want in each Docker deployment VM.
   3. In Region, select the region that's closer to you geographically.
      The drop-down list displays regions your OCI account is subscribed to.
   4. In Shape, select the Docker deployment VM's shape.

      As this is your first Docker deployment VM, the Docker Management VM is also created with the same shape. For the image management VM's optimum performance, select a shape with at least 2 OCPUs and 16 GB memory.

      Wait for a few seconds. VB Studio calculates the number of Compute VM instances that can be created with the selected shape and displays it in the dialog box. If the required number of Compute VM instances aren't available, choose another shape.
   5. In Volume, specify the storage capacity for each Docker deployment VM.
   6. If you've selected a Flex shape, then in Number of OCPUs, specify the number of OCPUs to add in each Docker deployment VM.
   7. If you've selected a Flex shape, then in Amount of Memory, specify each Docker deployment VM's memory.
7. For VCN Select, choose Default or Custom.
   • If you chose Default, click Migrate. You are finished with this task.
   • If you chose Custom, continue to the next step.
8. Fill out the additional details for the custom VCN:
   1. VCN Compartment: Select the compartment.
      If you're an Oracle Cloud OS Management Service (OSMS) user, don't select the OSMS compartment or a compartment with an OSMS policy.
   2. VCN: Select the VCN.
   3. Subnets Compartments: Select the compartments where your public subnets are. By default, it adds your VCN's compartment. If required, you can add more compartments.
   4. Subnets: Select a subnet. The list shows public subnets only.
      You can add multiple public subnets. If VB Studio can't create a Docker executor on the first subnet you've added, it tries to create it on the second subnet, and so on.
9. Click Validate Network Setup.
10. Click Migrate.

In VB Studio, you can import a Docker image from an external Docker registry or create a Docker image from a build executor template.

You will need to configure VB Studio to connect to your OCI account before you can proceed. See Set Up the OCI Connection in VB Studio.

VB Studio provides out-of-the-box base Docker images for your organization's users. You can't modify or delete these Docker images, and they can't be used for building your job. These base images are used to create Docker images from Docker build executor templates.

You can create and manage Docker images from the Build Executors tab on the Organization page.

1. In the navigation menu, click Organization .
2. Click the Build Executors tab.
3. Click the Docker Images tab.

This table describes the actions you can perform to create and manage Docker images.

Action	How To
Import a Docker image from an external Docker registry	Click Create Image and select Create Image from Registry. In the Add Custom Docker Image dialog box, in Name, enter the image's name. In Registry Host, enter the Docker registry's host name. In Username and Password, enter the credentials of the users who can access the registry. If it's a public registry, leave the fields empty. In Image Name, enter the Docker image's name to be imported. In Version Tag, specify the Docker image's tag In Max Executors, specify the maximum number of executors to be created from the imported image. Click Add.
Create a Docker image from an executor template	You can create only one Docker image from an executor template. Click Create Image and select Create Image from Build Executor Template. From the Build Executor Template drop-down list, select the executor template. In Max Executors, specify the maximum number of executors to be created from the image. Click Save.
Change a Docker image's executor template	Click Action and select Edit. In Build Executor Template, change the template and click Save.
Change a Docker image's maximum executors	Click Action and select Edit. In Max Executors, change the number of executors and click Save.
Re-create a Docker image	Click Action and Recreate Image. In the confirmation dialog box, click OK.
View a Docker image's log	Click Action and select Show Log.
Delete a Docker image	Click Action and select Delete. In the Delete Docker Image dialog box, click Delete.

You can add and manage Docker deployment VMs from the Organization Administration page's Build Executors tab.

1. In the navigation menu, click Organization .
2. Click the Build Executors tab.
3. Click the VM Pool tab and follow one of these procedures:
   • To add Docker deployment VMs after you have added the initial VM, see Add Docker Deployment VMs.
   • To view, start, stop, delete, or view the Docker VM logs, see Manage Docker VMs.
   • To manage disk usage for a Docker VM, see Manage Docker VM Resources.

If you want to run your organization's builds on VM build executor, you can reset Docker on the Management VM from the Organization page's Build Executors tab.

1. In the navigation menu, click Organization .
2. Click the Build Executors tab.
3. Click the VM Pool tab.
4. For the Management VM, click and select Reset.
5. In the Delete Docker Deployment VM dialog box, click OK.

When you switch OCI accounts or change from using the Free VM account to using an OCI account, you may need to manually set up the OCI account and then connect it to VB Studio.

1. Open the OCI console and, in the upper-left corner, click Navigation Menu .
2. Select Identity & Security and then, under Identity, select Compartments.
3. On the Compartments page, create a compartment to host VB Studio resources.
   1. To create the compartment in the tenancy (root compartment), click Create Compartment.
   2. In the Create Compartment dialog box, fill in the fields and click Create Compartment.
   To learn more about compartments, see Managing Compartments.
4. Create a user that can access the VB Studio compartment:
   1. In the navigation menu, select Identity & Security.
   2. Under Identity, select Users.
   3. Click Create User.
   4. Select the IAM user type.
   5. In the Create User dialog box, fill in the fields, then click Create.
   To learn more about OCI users, see Managing Users.
5. On your computer, generate a private-public key pair in the PEM format.
   To find out how to generate a private-public key pair in the PEM format, see How to Generate an API Signing Key.

   Here's an example of private-public key files on a Windows computer:

   
   

   
   

   
   
6. Upload the public key to the user's details page:
   1. Open the public key file in a text editor and copy its contents.
   2. In the navigation menu, select Identity and Security.
   3. Under Identity, select Users.
   4. Click the user's name created in Step 4.
   5. Under Resources, click API Keys.
   6. Click Add API Key.
   7. In the Add API Key dialog box, select the Paste Public Key option, paste the contents of the public key file, then click Add.
   To learn more about uploading keys, see How to Upload the Public Key.
7. On the Groups page, create a group for the user who can access the VB Studio compartment and add the user to that group:
   1. In the navigation menu, select Identity and Security.
   2. Under Identity, select Groups.
   3. Click Create Group.
   4. In the Create Group dialog box, fill in the fields and click Create.
   5. On the Groups page, click the group's name.
   6. On the Group Details page, click Add User to Group.
   7. In the Add User to Group dialog box, select the user created in Step 4 and click Add.
   To learn more about groups, see Managing Groups.
8. In the root compartment, not the VB Studio compartment, create a policy to allow the group created in step 6 to access the VB Studio compartment.
   1. In the navigation menu, select Identity and Security.
   2. Under Identity, select Policies.
   3. On the left side of the Policies page, from the Compartment list, select the root compartment.
   4. Click Create Policy.
   5. In Name and Description, enter a unique name and a description.
   6. In Compartment, select the root compartment.
   7. In Policy Builder, click Show manual editor and add these statements:
      • allow group <group-name> to manage all-resources in compartment <compartment-name>

        This grants all permissions to the VB Studio group users to manage all resources within the VB Studio compartment.

      • allow group <group-name> to read all-resources in tenancy

        This grants read permissions to the VB Studio group so that its users can read—but not use, create or modify—all resources inside and outside the VB Studio compartment. The group users can't use, create, or modify the resources.

      Here's an example:

      
      

      
      

      
      
   8. Click Create.
   To learn more about policies, see Managing Policies.

Every OCI resource has a unique Oracle-assigned ID called an Oracle Cloud Identifier (OCID). You'll need and use this information (and more) to set up the OCI connection in VB Studio.

To connect to OCI, you need the account's tenancy OCID, home region, the OCID of the compartment that hosts VB Studio resources, and the OCID and the fingerprint of the user who can access the VB Studio compartment. To connect to OCI Object Storage, you need the Storage namespace. You can get these values from the OCI Console pages.

This table describes how to get the OCI input values required for the connection.

Before you can connect to OCI, you must first get the compartment's details, user details, and the required OCID values. You need to exit VB Studio and open the OCI console to retrieve the details you need. If you're not the OCI administrator, you need to get the details from the OCI administrator.

1. In the navigation menu, click Organization .
2. Click the OCI Account tab.
3. Click Connect.
4. In Tenancy OCID, enter the tenancy's OCID copied from the Tenancy Details page.
5. In User OCID, enter the OCID of the user who can access the VB Studio compartment.
6. In Home Region, select the home region of the OCI account.
7. In Private Key, enter the user's private key who can access the VB Studio compartment.
   The private key file was generated and saved on your computer when you created the private-public key pair in the PEM format. See step 5 in Set Up the OCI Account.

   Make sure that the private key you enter contains the -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- markers.

8. In Passphrase, enter the passphrase used to encrypt the private key. If no passphrase was used, leave the field empty.
9. When you enter a private key and a passphrase, the Fingerprint field is automatically populated. Ensure that the automatically populated fingerprint value matches the fingerprint value of your private-public key pair. If it doesn't, update it to enter the correct value.
10. In Compartment OCID, enter the compartment's OCID copied from the Compartments page.
11. In Storage Namespace, enter the Object Storage Namespace value copied from the Tenancy Details page.
12. Select the terms and conditions check box.
13. Click Validate.
14. After validating the connection details, click Save.

Here's an example of an OCI Account tab filled with required OCI details.