2 Set Up Oracle Visual Builder Studio to Manage Your Development Cycle

Like other Oracle Cloud services, you must create an instance of Oracle Visual Builder Studio (VB Studio) before you can start using it. You can create only one instance in an Oracle Cloud account.

Before You Begin

Before you set up VB Studio, ensure that you are assigned the correct roles in Oracle Identity Cloud Service (IDCS).

You must be assigned this role: To ...
Cloud Administrator Set up Oracle Cloud Infrastructure (OCI) compartments and buckets. OCI compartments and buckets are required to set up the VB Studio build system.

If you're not assigned the role, you must belong to the OCI_Administrator group in OCI.

Identity Domain Administrator or User Administrator Add users and assign IDCS roles.

If you're not an administrator, make sure that your OCI group is assigned a policy like this:

Allow group MyGroup to inspect identity-providers in tenancy

DEVCS_APP_ENTITLEMENT_ADMINISTRATOR Create the VB Studio instance
DEVELOPER_ADMINISTRATOR Set up VB Studio. After you're assigned the role, you're also called the VB Studio's Organization Administrator.
Compute.Compute_Operations and Storage.Storage_Administrator Create and manage VMs on OCI Compute Classic and store artifacts on OCI Object Storage Classic. The role is required only if you're an OCI Classic user.

Create the VB Studio Instance

You can create one only one VB Studio instance in an Oracle Cloud account, so make sure you don't already have one before you get started.

  1. In a web browser, go to https://cloud.oracle.com/sign-in.
    To view the list of supported browsers, see https://docs.cloud.oracle.com/iaas/Content/GSG/Tasks/signingin.htm#supported_browsers.
  2. On the Sign-In page, in Account, enter your account name and click Next.
  3. On the Oracle Cloud Account sign-in page, enter your Oracle Cloud account credentials and click Sign In.
    The Oracle Cloud Console, also called the Oracle Cloud Infrastructure console or OCI console, opens.
  4. In the upper-left corner, click Navigation Menu the Menu icon.
  5. Under More Oracle Cloud Services, select Platform Services, and then select Visual Builder Studio.
  6. In the Instances tab, click Create Instance.
  7. On the Create New Instance page, in Instance, enter a unique name. In Description, enter a description.
    The name helps you to identify the service instance.
  8. In Notification Email, enter your email address where you'd like to receive email notification when the instance is ready.
  9. In Region, select your home region.
    You'll find your region on the OCI console's header.
  10. Click Next.
  11. On the Service Details page, verify the entered details and click Next.
  12. On the Confirmation page, click Create.
    Expand the Instance Create and Delete History section to track the status.
Once the service instance is created, you can open the service console by clicking Action the Action menu icon and then selecting Access Service Instance.

The VB Studio Organization page opens. Click the OCI Credentials link or the OCI Account tab to configure OCI connections before you create a project.

Access VB Studio from the Oracle Cloud Home Page

You can sign in to and open VB Studio from the Oracle Cloud home page:

  1. In a web browser, go to https://cloud.oracle.com/sign-in.
  2. On the Sign-In page, in Account, enter your Oracle Cloud account or tenancy name and click Next.
  3. On the Oracle Cloud Account sign-in page, enter your Oracle Cloud account credentials and click Sign In.
    The Oracle Cloud Console, also called the OCI console, opens.
  4. In the upper-left corner, click Navigation Menu the Menu icon.
  5. Under More Oracle Cloud Services, select Platform Services and then select VB Studio.
  6. On the Instances tab, click Manage this instance the Action menu icon and select Access service instance.

If you’re signing in to VB Studio for the first time, you should have received an email with the subject Verify your Oracle Visual Builder Studio email. Open the email and click the URL link in the email body to verify your email. This is required to receive email notifications from the service.

After your email address is verified, you’ll receive another email with the subject Welcome to Oracle Visual Builder Studio. This email contains the VB Studio URL that you can bookmark.

After you sign in to VB Studio, you'll see the Organization page that displays all the projects you're a member of, as well as your favorite projects, the projects you own, and all the shared projects in your organization.

From the Organization page, you can manage all projects, OCI connections, virtual machines, and the properties of the organization. To open a project, click its name. You can't open a project if you're not a member.

Connect to OCI or OCI Classic

You need to connect to the Oracle Cloud Infrastructure Compute (OCI Compute) or Oracle Cloud Infrastructure Compute Classic (OCI Compute Classic) because they provide the virtual machines (VMs) on which VB Studio runs its builds.

You need to connect to Oracle Cloud Infrastructure Object Storage (OCI Object Storage) or Oracle Cloud Infrastructure Object Storage Classic (OCI Object Storage Classic) because they are used to store build and Maven artifacts for VB Studio projects.

If you're an OCI user, set up connections to OCI Compute and OCI Object Storage. VB Studio runs its builds on OCI Compute VMs, and stores build and Maven artifacts in the OCI Object Storage buckets.

If you're an OCI Classic user, set up connections to OCI Compute Classic and OCI Object Storage Classic. VB Studio runs its builds on OCI Compute Classic VMs, and stores build and Maven artifacts in the OCI Object Storage Classic containers.

Set Up the OCI Connection

Before you set up the connections, set up your OCI account to host and manage necessary resources, such as VMs for your builds and storage buckets for your project data.

To set up the OCI account, open the OCI console and create a compartment, a group and a user to access the compartment, and a policy that defines access to the compartment.

You can use the root compartment and the tenancy user that was created when the OCI account was created, but it's recommended to create a dedicated compartment to host VB Studio resources. This allows you to organize VB Studio resources better because they aren't mixed with the other resources of your tenancy. You can also restrict users and control read-write access to the compartment without affecting other resources. To learn more about compartments, see Understanding Compartments.

After setting up your OCI account, share the compartment's and the created user's details with the VB Studio Organization Administrator to set up the OCI connection in VB Studio.

Set Up the OCI Account
  1. On the OCI console, in the upper-left corner, click Navigation Menu the Menu icon.
  2. Under Governance and Administration, select Identity, and then 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 Working with Compartments.
  4. Create a user to access the VB Studio compartment.
    1. In the left navigation menu, under Governance and Administration, click Identity, and then click Users.
    2. Click Create User.
    3. In the Create User dialog box, fill in the fields and click Create.
    To learn more about OCI users, see Working with 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 left navigation menu of the OCI console, under Governance and Administration, click Identity, and then click Users.
    3. Click the user's name created in Step 4.
    4. In the User Details page, click Add Public Key.
    5. In the Add Public Key dialog box, 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 the group.
    1. In the left navigation menu, under Governance and Administration, go to Identity, and click Groups.
    2. Click Create Group.
    3. In the Create Group dialog box, fill in the fields and click Submit.
    4. On the Groups page, click the group's name.
    5. On the Group Details page, click Add User to Group.
    6. In the Add User to Group dialog box, select the user created in Step 4 and click Add.
    To learn more about groups, see Working with 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, under Governance and Administration, click Identity, and then click Policies.
    2. On the left side of the Policies page, from the Compartment list, select the root compartment.
    3. Click Create Policy.
    4. In Name and Description, enter a unique name and a description.
    5. In Policy Statements, 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:

    6. Click Create.
    To learn more about policies, see Working with Policies.
Get the Required OCI Input Values

Every Oracle Cloud Infrastructure resource has an Oracle-assigned unique ID called an Oracle Cloud Identifier (OCID).

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.

To get these values ... Do this:
Tenancy OCID, Home Region, and Storage Namespace Open the OCI console. In the navigation menu, under Governance and Administration, select Administration, and then select Tenancy Details.

The Tenancy Information tab displays the tenancy OCID in OCID, the home region in Home Region, and the storage namespace in Object Storage Namespace.

Here's an example:

User OCID and Fingerprint Open the OCI console. In the navigation menu, under Governance and Administration, select Identity, and then select Users. On the Users page, click the user's name.

The User Information tab displays the user OCID in OCID. Click the Copy link to copy it to the clipboard.

Here's an example of vbstudio.user:

To get the fingerprint of the public key associated with your OCI account, scroll down to the API Keys section and copy the fingerprint value.

Compartment OCID Open the OCI console. In the navigation menu, under Governance and Administration, select Identity, and then select Compartments. On the Compartments page, click the compartment's name.

The Compartment Information tab displays the compartment's OCID in OCID. Click the Copy link to copy the compartment's OCID to the clipboard.

Here's an example:

Set Up the OCI Connection in VB Studio

To connect to OCI, get the VB Studio compartment's details, user details, and the required OCID values. Then, create an OCI connection from VB Studio. If you're not the OCI administrator, get the details from the OCI administrator.

  1. In the navigation menu, click Organization Organization.
  2. Click the OCI Account tab.
  3. Click Connect.
  4. In Account Type, select OCI.
  5. In Tenancy OCID, enter the tenancy's OCID copied from the Tenancy Details page.
  6. In User OCID, enter the OCID of the user who can access the VB Studio compartment.
  7. In Home Region, select the home region of the OCI account.
  8. In Private Key, enter the private key of the user 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.
  9. In Passphrase, enter the passphrase used to encrypt the private key. If no passphrase was used, leave the field empty.
  10. In Fingerprint, enter the fingerprint value of the private-public key pair.
  11. In Compartment OCID, enter the compartment's OCID copied from the Compartments page.
  12. In Storage Namespace, enter the storage namespace copied from the Tenancy Details page.
  13. To agree to terms and conditions, select the terms and conditions check box.
  14. To validate the connection details, click Validate.
  15. After validating the connection details, click Save.
Here's an example of an OCI Account tab filled with required OCI details.

Set Up the OCI Classic Connection

To connect to OCI Classic, you need the credentials of a user with the Compute.Compute_Operations and Storage.Storage_Administrator identity domain roles along with the service ID and Authorization URL of OCI Object Storage Classic.

The Compute.Compute_Operations role enables you to create, update, and delete VMs on OCI Compute Classic. The Storage.Storage_Administrator role enables you to store artifacts on OCI Object Storage Classic.

Before you create the OCI Compute Classic connection, you must check the Compute_Operations Role: Terms of Use and get the Service ID and the authorization URL of OCI Object Storage Classic:

Get OCI Object Storage Classic Input Values
  1. Open the Oracle Cloud Dashboard.
  2. In the Storage Classic tile, click Actionthe Action menu icon and select View Details.

    If the Storage Classic tile isn’t visible, click Customize Dashboard. Under Infrastructure, find Storage Classic, click Show, and then close the Customize Dashboard window.

  3. On the Service Details page, in the Additional Information section of the Overview tab, note the values of the Auth V1 Endpoint URL and the last part of the REST Endpoint URL.

    If you’re using an Oracle Cloud traditional account, the fields shown in this graphic might differ from the fields on your Service Details page.

    Description of storage_cloud_console.png follows
    Description of the illustration storage_cloud_console.png

Create an OCI Classic Connection from VB Studio

After you have the required values, create an OCI Classic connection from VB Studio.

  1. Sign in to VB Studio.
  2. In the navigation menu, click Organization Organization.
  3. Click the OCI Account tab.
  4. To create a connection, click Connect. To edit the connection details, click Edit.
  5. In Account Type, select OCI Classic.
  6. In the OCI Object Storage Classic section, fill in the required details.
    1. In Service ID, enter the value copied from the last part of the REST Endpoint URL field of the Service Details page.
      For example, if the value of the REST Endpoint URL is https://demo12345678.storage.oraclecloud.com/v1/Storage-demo12345678, then enter Storage-demo12345678.
    2. In Username and Password, enter the credentials of the user assigned the Storage.Storage_Administrator identity domain role.
    3. In Authorization URL, enter the URL copied from the Auth V1 Endpoint field of the Service Details page.
      Example: http://storagetria01234-usoracletria12345.storage.oraclecloud.com/auth/v1.0.
    4. Click Validate.
  7. In the OCI Compute Classic section, fill in the required details.
    1. In Username and Password, enter the credentials of the user who’s assigned the Compute.Compute_Operations identity domain role.
    2. To agree to terms and conditions, select the terms and conditions check box.
    3. Click Validate.
  8. Click Save.
Compute_Operations Role: Terms of Use

Here are some special legal terms and guidance that apply to the usage of the Compute_Operations role for VB Studio.

In addition to these VB Studio terms, you should follow security best practices in maintaining the security of the username and password.

  • You must create a dedicated username and password for use by VB Studio. When creating a username, avoid including personal names or personal information (like birthdays). Your password should always be complex and impossible to guess.

  • You understand that a user with the Compute_Operations role can view, create, update and delete OCI Compute Classic resources such as VM instances, storage volumes, security rules, and security IP lists. Your failure to maintain security best practices to secure the username and password of the user with the Compute_Operations role may create a high risk for you and your organization.

  • You should assign the Compute_Operations role privileges only to the username created for VB Studio.

  • Notwithstanding VB Studio terms, you acknowledge that Oracle isn’t responsible or liable for any action you take in accessing or creating access to the VB Studio or OCI Compute Classic.

Set Up the Build System

VB Studio builds run on OCI Virtual Machines (VMs), also called as Build VMs. The Build VMs run in a public subnet of an OCI Virtual Cloud Network (VCN). Before your organization’s members can run builds, you must set up a VCN to run Build VMs, create Build VM templates, and then allocate Build VMs to those templates.

If you're new to OCI Networking, see Overview of Networking to learn about OCI networking concepts such as VCN and subnets.

What Are Build VMs and Build VM Templates?

A Build Virtual Machine (VM) is an OCI Compute or OCI Compute Classic VM that runs builds of jobs defined in VB Studio projects. A Build VM Template defines the operating system and software installed on Build VMs.

Before your organization's members create jobs and run builds, you should first create Build VM templates with software that the organization's members use. After creating the templates, allocate Build VMs to each Build VM template.

When you define a Build VM template, you specify:

  • The VM's operating system

    You can choose from Oracle Linux 6 and Oracle Linux 7.

  • Software and their versions

    To find the list of software packages and their versions available in VB Studio, see Software Installed on the Build Executor.

When you add a Build VM, you specify:

  • The Build VM template

    When a Build VM starts, VB Studio installs the operating system and the software you've defined in the template on the VM.

  • The VM's OCI region

    Oracle Cloud Infrastructure is hosted in regions and availability domains. A region is a localized geographic area, and an availability domain is one or more data centers located within a region. Remember, a Build VM is a VM on OCI Compute. To learn more about regions and availability domains, see Regions and Availability Domains.

  • The VM's shape

    A shape is a template that determines the number of CPUs, amount of memory, and other resources allocated to a newly created instance. To learn more about shapes, see VM Shapes.

  • The VM's Virtual Cloud Network (VCN)

    A VCN is a software-defined network that you set up in the Oracle Cloud Infrastructure data centers in a particular region. To find more about VCNs and subnets, see VCNs and Subnets.

When the organization's members create jobs, they simply associate the appropriate Build VM template with each job. The Build VM starts automatically when a build runs on it and stops after its sleep timeout period. You can manually start and stop it too.

When a build runs:

  1. The build executor checks the job's Build VM template and then looks for the VM that's allocated to the template:
    • If a VM is available, the build executor immediately runs the build on the VM.
    • If all VMs are busy running builds of other jobs using the same Build VM template, the build executor waits until a VM becomes available and then runs the current job's build on it.
    • If a VM doesn't exist, the build executor reports an error.
  2. If the build runs on a VM for the first time or after a VM wakes up after its sleep timeout period, the build executor installs the software defined in the Build VM template before it runs the build. This takes time.
  3. Depending on how the job is configured, after installing the software, the executor clones the job’s Git repositories to the VM, runs the defined build steps, creates artifacts, and performs post-build steps.
  4. After the build completes, the executor copies any generated artifacts to the OCI Object Storage bucket or the OCI Object Storage Classic container.
  5. The Build VM waits for a period of time for any queued builds. If no builds run in the wait time period, the Build VM uninstalls its software and stops.

Build VMs in Virtual Cloud Network

A Build VM runs in a Virtual Cloud Network (VCN). You can run Build VMs in the VB Studio's default VCN, or in your VCN.

If you don't have a VCN or want to use the default option without any additional configuration, use the VB Studio default VCN. If you want Build VMs to access services that are running in your VCN, then run Build VMs in your VCN.

Use VB Studio's Default VCN

If you don't have a VCN, you should use VB Studio's default VCN to run your Build VMs.

VB Studio's default VCN resides in the compartment you created and configured in Set Up the OCI Connection. When a Build VM that uses the default VCN starts, VB Studio creates a VCN called dcs-slave-vcn with CIDR block 10.0.0.0/16.

When VB Studio creates the default VCN, it also creates these components and adds them to the VCN:

  • An Internet Gateway
  • A Route Table that uses the Internet Gateway as the routing rule
  • A Security Rule with these rules:
    • Ingress: Allow TCP traffic on destination port 22 (SSH), 9003 (Executor agent debug), 9005 (VM agent debug), 9082 (Executor agent), and 9085 (VM agent) from source 0.0.0.0/0 and any source port.
    • Egress: To any destination from any protocol
  • Three subnets, one for each availability domain. Their CIDR is set to 10.0.0.0/24, 10.0.1.0/24, and 10.0.2.0/24.

As soon as the default VCN is available, you have full control over it and can modify it. You can add private subnets for your private services, add more public subnets or delete the existing subnets, modify security lists, and add or remove other components.

Note:

  • If you modify the default VCN, make sure that at least one public subnet is available in the VCN. If there are no public subnets, Build VMs in the default VCN won't run and your builds will fail.
  • The default VCN is created once and continues to stay until it is deleted manually.
  • If your organization's members configure jobs that access services in the private or public subnets of the VCN, ask them to configure their jobs to access the services using private IPs or Fully Qualified Domain Name (FQDN).
Run Build VMs in Your VCN

If you run Oracle Cloud services in your VCN, you should configure your VCN to run VB Studio Build VMs so your services and Build VMs are in the same VCN. This lets Build VMs access your Oracle Cloud services easily without any complex networking configuration.

Before you configure your VCN, make a note of these:

  • In your VCN, create a public subnet or configure an existing public subnet to allow inbound access from and outbound access to VB Studio.
  • When you're creating or configuring a public subnet, make sure it is regional.
  • Instead of modifying an existing security list's security rules, you should create a new security list for the public subnet.

    For the public subnet, create a security list and add ingress rules from source CIDR 0.0.0.0/0 for VB Studio ports 22 (SSH), 9082 (Executor Agent), and 9085 (VM Agent). This is required to allow VB Studio access the Build VMs in your VCN.

  • If your VCN isn't in the same compartment that VB Studio is in, make sure that the user whose OCID you've specified in Set Up the OCI Connection in VB Studio is assigned the use virtual-network-family policy for the VCN's compartment. This is required for networking permissions and builds to run in your VCN. This statement assigns the policy to the user's group:

    allow group <group-name> to use virtual-network-family in compartment <vcn-compartment-name>

    Here's an example of the use virtual-network-family policy added to the policies you created in Set Up the OCI Account.

    VBStudio policies in OCI
  • Make sure that your VCN has a route table with a rule that allows Internet access.
  • To allow Build VMs access your private subnet's services and resources, configure the private subnet's security rules to allow incoming traffic from the public subnet used by Build VMs.
  • After adding Build VMs to your VCN, ask your organization's members to configure their build jobs to use the private IP addresses or the Fully Qualified Domain Name (FQDN) of services that are running in the VCN.

    Tell them not to use public IP addresses, because when Build VMs are in the same VCN as the service, public IP addresses will route the traffic outside the VCN, causing builds to fail.

Build VMs run in a VCN's public subnet. This table describes what you need to do if you have a VCN.

If ... Then :
You have a VCN without a public subnet
  1. Create and Configure a Public Subnet in Your VCN.

    You'll also configure the subnet's security list to allow inbound access from and outbound access to VB Studio.

  2. To allow Build VMs access a service running in your private subnet, configure the private subnet's security list. See Allow Build VMs to Access Your Private VCN Resources.
  3. Add and Manage Build VMs in your VCN.
You have a VCN with a public subnet
  1. In your VCN, create a security list with ingress rules and egress rules, as described in steps 6-11 of Create and Configure a Public Subnet in Your VCN.
  2. Open your public subnet's details page and add the security list. See 13 of Create and Configure a Public Subnet in Your VCN.
  3. To allow Build VMs access services running in your private subnet, configure the private subnet's security list. See Allow Build VMs to Access Your Private VCN Resources.
  4. Add and Manage Build VMs in your VCN.
You don't have a VCN and want to create one
  1. Use the VCN wizard to create a VCN with a public subnet and an internet gateway. See Virtual Networking Quickstart.
  2. Create and Configure a Public Subnet in Your VCN.

    You'll also configure the subnet's security list to allow inbound access from and outbound access to VB Studio.

  3. To allow Build VMs access services running in your private subnet, configure the private subnet's security list. See Allow Build VMs to Access Your Private VCN Resources.
  4. Add and Manage Build VMs in your VCN.
Create and Configure a Public Subnet in Your VCN

Before you can run Build VMs in your VCN, you must first create a public subnet in your VCN with security rules that allow inbound access from and outbound access to VB Studio.

  1. Sign in to Oracle Cloud Console.
  2. On the OCI console, in the upper-left corner, click Navigation Menu the Menu icon.
  3. Under Core Infrastructure, select Networking, and then select Virtual Cloud Networks.
  4. Under List Scope, select the compartment.
  5. From the VCNs list, click the VCN's name.
  6. Under Resources, click Security Lists, and then click Create Security List.
  7. In Name, enter a name for the security list.
  8. In Create in Compartment, ensure that the correct compartment is selected.
  9. In Allow Rules for Ingress, click + Additional Ingress Rule and follow these steps:
    1. In Source Type, select CIDR.
    2. In Source CIDR, enter 0.0.0.0/0.
    3. In Destination Port Range, enter 9082.
    4. (Optional) In Description, add a description.
    5. Click + Additional Ingress Rule and repeat steps from 9.a to 9.d to add ports 9085 and 22.
  10. In Allow Rules for Egress, click + Additional Egress Rule and follow these steps:
    1. In Source Type, select CIDR.
    2. In Source CIDR, enter 0.0.0.0/0.
    3. In IP Protocol, select All Protocols.
    4. (Optional) In Description, add a description.
  11. Click Create Security List.
    After creating the security list, click its name to verify the ingress and egress rules you added.

    Here's an example of ingress rules:

    Here's an example of the egress rule:

  12. Under Resources, select Subnets and follow these steps to create a public subnet:
    If you want to edit an existing public subnet, jump to the next step.
    1. Click Create Subnet.
    2. In Name, enter the subnet's name.
    3. In Subnet Type, make sure that Regional is selected.
    4. In CIDR Block, enter the subnet's CIDR block.
      Don't set it to 172.17.0.0/16 as it's the default subnet allocated to Docker.
    5. In Route Table, select the VCN's route table.
    6. In Subnet Access, make sure that Public Subnet is selected.
    7. In DHCP Options, select the VCN's DHCP options.
    8. In Security List, select the security list you created in Step 6.
    9. Fill in the other fields.
    10. Click Create Subnet.
  13. If you want to edit an existing subnet, follow these steps:
    1. Under Resources, select Subnets and click the public subnet's name.
    2. Click Add Security List.
    3. In the Add Security List dialog box, in Security List, select the security list you created in Step 6.
    4. Click Add Security List.
That's it. After creating or editing the public subnet, your Build VMs can now run in your VCN.
Allow Build VMs to Access Your Private VCN Resources

After adding a public subnet in your VCN, if you want Build VMs to access the resources and services (such as Java Cloud Service or a VM-based Database) running in the VCN's private subnet, configure the private subnet's security rules to allow incoming traffic from the public subnet used by Build VMs.

For example, to allow Build VMs access Java Cloud Service running in a private subnet, configure the subnet's security list to add the Build VMs CIDR ranges to the Ingress rule associated with the JCS Admin port.

  1. Sign in to Oracle Cloud Console.
  2. On the OCI console, in the upper-left corner, click Navigation Menu the Menu icon.
  3. Under Core Infrastructure, select Networking, and then select Virtual Cloud Networks.
  4. On the Virtual Cloud Networks page, click the VCN.
  5. Under Resources, click Security Lists, and then click the private subnet's security list.
  6. Click Add Ingress Rules.
    If you want to modify an existing rule, click the Actions icon (three dots), and then select Edit.
  7. In Source Type, select CIDR.
  8. In Source CIDR, enter the Build VMs public subnet's CIDR range.
  9. In Destination Port Range, enter the service's port number.
  10. (Optional) In Description, add a description.
    Here's an example of Java Cloud Service port 7002 with a source CIDR of 10.0.4.0/24:
  11. Click Add Ingress Rules.
  12. If required, repeat steps from 6 to 11 for each service's port.

Create and Manage Build VM Templates

You can create and manage Build VM templates from the VM Templates page in Organization Administration.

Action How To

Create a Build VM template

  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines Templates tab.

  3. Click + Create Template.

  4. In the New VM Template dialog box, enter a name and description of the VM template. In Platform, select the operating system to run on the VM.

  5. Click Create.

Configure a VM template’s software
  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines Templates tab.

  3. Select the template and click Configure Software.

  4. If necessary, in Filter Software Packages, enter the search term and click the Search icon.

    To see the latest version of the software, select the Show latest versions only check box. This is helpful if multiple versions of the same software are available in the catalog.

  5. In the Software Catalog, click Add Add.

    If a software is dependent on another software, a message informs you about the dependencies that must be added along to use the software.

  6. Click Done.

Edit a VM template's name or description
  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines Templates tab.

  3. Select the template and click Edit.

  4. In the Edit VM Template dialog box, update the name or description.
  5. Click Save.

Delete a VM template

When you delete a VM template, its Build VMs are deleted too.

  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines Templates tab.

  3. Select the template and click Delete the Delete icon.

  4. In the Delete VM dialog box, click Yes to confirm.

Add and Manage Build VMs

When you add a Build VM, you allocate a VM on the linked OCI Compute or OCI Compute Classic to run builds of jobs.

Tip:

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

You should also make sure that all VMs of a specific Build VM template run in the same VCN. If you add VMs in different VCNs, your builds might behave unpredictably.

You can always return to the Virtual Machines tab to add or remove VMs, based on your actual usage. Note that the more VMs you have running at a specific time, the higher the cost. To minimize the higher cost, use the Sleep Timeout setting on the Virtual Machines page to automatically shut down inactive VMs.

Each build runs in one build executor, or one VM. You can build up to 99 builds in parallel using the same Build VM template.

To add Build VMs, you'll need these details:

  • Build VM template's name that defines the software to be installed on Build VMs. Make sure that the template has the correct software.
  • OCI region where you have authorization to add Build VMs. To learn more about regions and availability domains, see Regions and Availability Domains.
  • VM's shape. To learn more about shapes, see VM Shapes.
  • VM's VCN, if you want to run it in another VCN than the VB Studio's default VCN. To find more about VCNs and subnets, see VCNs and Subnets.
Action How To
Find VMs that use a particular template
  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines tab.

  3. From the Sort By list, select Template to sort the VMs in the Build VMs tab.
  4. Scroll down and search the list for the template's name.

You might find multiple VMs that use the same VM template.

Add a Build VM in the VB Studio's default VCN

  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines tab.

  3. Find whether any VMs that use the VM template already exist.

    If you don't find VMs using the VM template, jump to Step 4. If you find one or more Build VMs that uses the VM template, follow these steps:

    1. In the Details column of the Build VM, click Show Machine Details Details.
    2. Note the VCN's name.

      Here's an example:

      Build VM's details

      The VM's name is displayed for VMs that are in the Available state. If the VM is in the Stopped or the Pendingstate, start it. Click the Actions Menu icon and select Start.

      If the VCN's name isn't dcs-slave-vcn, delete the VM or use another VM template. You should not add Build VMs to different VCNs that use the same Build VM template.

      To delete the VM, click the Actions Menu icon and select Delete.

  4. In the Build VMs tab, click + Create VM.

  5. In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate.

  6. In VM Template, select the Build VM template.
  7. In Region, specify the VM's region.
  8. In Shape, select the VM's shape.
  9. In VCN Selection, select Default.
  10. Click Add.

After adding Build VMs, you can configure the jobs to use the VM template.
Add a Build VM in your VCN Before you add a VM, make sure that you've added a public subnet in your VCN. See Create and Configure a Public Subnet in Your VCN.
  1. In the navigation menu, click Organization Organization.

  2. In the Virtual Machine Templates tab, make sure that the Build VM template has the correct software.
  3. Click the Virtual Machines tab.

  4. Find whether any VMs that use the VM template already exist.

    If you don't find VMs using the VM template, jump to Step 4. If you find one or more Build VMs that uses the VM template, follow these steps:

    1. In the Build VM's Details column, click Show Machine Details Details.
    2. Note the VCN's name.

      Here's an example:

      User VCN's details

      The VM's name is displayed for VMs that are in the Available state. If the VM is in the Stopped or the Pendingstate, start it. Click the Actions Menu icon and select Start.

      If the VCN is different from your VCN, delete the VM or use another VM template. You should not add Build VMs to different VCNs that use the same Build VM template.

      To delete the VM, click the Actions Menu icon and select Delete.

  5. In the Build VMs tab, click + Create VM.

  6. In the Add Build VM dialog box, in Quantity, specify the number of VMs you want to allocate.

  7. In VM Template, select the Build VM template.
  8. In Region, specify the VM's region.
  9. In Shape, select the VM's shape.
  10. In VCN Selection, select Custom.
  11. In VCN Compartment, select the compartment.
  12. In VCN, select the VCN.
  13. In Subnets, select a subnet. The list shows public subnets only.

    You can add multiple public subnets. If VB Studio can't create a Build VM on the first subnet you've added, it tries to create it on the second subnet, and so on.

  14. Click Add.

After adding Build VMs, you can configure the jobs to use the VM template.
View a Build VM’s log

The Build VM’s log has entries for all events along with information about when the events occurred, the type of event, and event details.

  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines tab.

  3. In the Build VMs tab, select the VM, click Actions the Actions Menu icon and select Display Log.

  4. In the Provisioning Log window, review the log.

    To download the log file to your computer, click Download Log.

Start or stop a VM manually When a build of a job triggers, its VM starts automatically if it was in the stopped state. It takes some time to start a VM, and the user must wait for a VM to start before the job's build runs on it. Similarly, a VM stops automatically if no builds run on it during the sleep timeout period.

At times, you may want to manually start a VM before triggering a job's build or stop it to free resources immediately.

  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines tab.

  3. In the Build VMs tab, select the VM, click Actions the Actions Menu icon and select Start or Stop.

Delete a Build VM

When you delete a Build VM, it waits for all builds running on it to complete and won't accept new builds while it’s waiting for the running builds to complete. After all the builds are complete, it shuts down and is removed.

  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines tab.

  3. In the Build VMs tab, select the VM, click Actions the Actions Menu icon and select Delete.

    To delete multiple VMs, select them using the Ctrl or Shift keys, click Update Selected and select Delete Selected VMs.

The deleted VMs are listed in the Deleted VMs tab.

Change the sleep timeout of all VMs The sleep timeout defines the duration (in minutes) a VM would be available in the active state if no builds run on it. By default, it is 1500 minutes.
  1. In the navigation menu, click Organization Organization.

  2. Click the Virtual Machines tab.

  3. Click Sleep Timeout.

  4. In the Sleep Timeout dialog box, change the timeout duration, and click Save.

Add Users to IDCS

To add users to VB Studio and its projects, make sure they are added to IDCS and assigned appropriate VB Studio roles.

If you want to federate with your existing identity provider, see Federating with Identity Providers.

To add users manually to IDCS, follow these steps:

  1. Open the Oracle Cloud Console page.
  2. In the upper-left corner, click Navigation Menu the Menu icon.
  3. Under Governance and Administration, select Identity, and then select Federation.
  4. On the Federation page, click the identity service provider's link.
  5. On the Identity Provider Details page, click Create IDCS User.
  6. In the Create IDCS User dialog box, enter the new user's details and click Create.
  7. To send the password reset instructions and URL to the new user, click Email Password Instructions.
  8. Click close.
  9. On the Identity Provider Details page, click the user's IDCS Username link.
  10. On the User Details page, click Manage Service Roles.
  11. On the Manage Service Roles page, search for the service with Developer Cloud Service description, click the Actions icon (three dots) and select Manage Instance Access.
  12. On the Manage Access page, in the Instance Role column, select the role you want to grant to the user.

    Assign the DEVELOPER_ADMINISTRATOR role to users who can administer VB Studio. Assign the DEVELOPER_USER role to other non-admin users. A user must be assigned one of these two roles to access VB Studio.

  13. Click Save Instance Settings.
  14. On the Manage Service Roles page, click Apply Role Settings.

For more details about adding users to IDCS and assigning them roles, see Managing Oracle Identity Cloud Service Users in the Console and Managing Instance Roles in the Console. To learn more about VB Studio IDCS roles, see IDCS Roles.

Manage the Organization

You can update your VB Studio organization’s name or description, manage projects, manage virtual machines (VM) and VM templates, and view the usage metric of projects.

Update the Organization’s Display Name and Description

By default, the organization's display name is <your_vbstudio_instance_name>-<your_oracle_account_name>.
  1. In the navigation menu, click Organization Organization.
  2. Click the Properties tab.
  3. In Name, edit the organization name.
  4. In the Confirm Organization Name Change dialog box, click Yes.
  5. In Description, if necessary, enter or edit the organization's description.

Set the Organization’s Default Wiki Markup Language

When you create a project, the project creation wizard displays the organization's default wiki markup language. If you don’t change the wiki markup language, the default markup language is used as the project’s markup language. You can change the default markup language for new projects, but note that existing projects continue to use their original markup language.

  1. In the navigation menu, click Organization Organization.
  2. Click the Properties tab.
  3. In Markup Language, select the default wiki markup language.

Manage Projects of the Organization

As the Organization Administrator, you can access and manage all projects. You can assign a project’s Project Owner role to yourself, delete a project, revoke the project's deletion, or postpone the project's deletion by a few days.

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

Example:

Here are the project management actions you can perform:

Action How To

Create a project

Click + Create.

See Create a Project.

Open a project In the Name column, click the project name.

See Open a Project.

You can open a project only if you're a member or an owner. Projects where you aren't a member or an owner don't appear as links. You can't open a project that's in the deleted state.

Search for a project Use the search box above the projects list.
Filter projects

In Member/Owner/Favorite/All, click a filter option to enable it.

Click the Member button to view projects where you're a member. Click Owner to view projects where you're a Project Owner. Click Favorite to view your favorite projects. Click All to view organization's all projects.

To see more filter options, click Detailed Filter the Filter icon.

Mark a project as a favorite In the Favorite column, click Favorite the Star iconto add it to your favorites list.
View a project's team members The Members column shows the gravatars of the project's team members. A blue circle around a user's gravatar indicates the user is assigned the project's Project Owner role. Click the gravatars to display names and email addresses of all team members.

Assign a project’s Project Owner role to yourself

You can assign a project’s Project Owner role to yourself. This is usually helpful in a case when all project's owners are removed or have left the organization. As the Organization Administrator, you can then take the ownership of such projects and then assign the Project Owner role to another project user.

For the project whose ownership you want to assign to yourself, click Update Project Actions and select Assign Me as Owner.

Delete a project

As the Organization Administrator, you can delete any project.

  1. For the project you want to delete, click Update Project Actions and select Delete.

  2. In the Delete Project dialog box, click Delete.

The project’s State is marked as Deleted - Project will be removed automatically in N days., but the project isn’t removed immediately. In the Delete Project dialog box, read the message before you click Delete. Also, check the project’s delete message to know when the project will be permanently removed. To immediately remove the project permanently, click Actions and select Remove Forever.

Postpone a deleted project's removal

At times, you may be unsure if you want to revoke a project's deletion that’s close to its permanent removal date. For such projects, you can choose to postpone their removal by a few days.

For the deleted project you want to postpone, click Update Project Actions and select Postpone Removal.

The project’s permanent removal date is rescheduled and the message is displayed at the top. In Status, check the project’s delete message to know when the project will be permanently removed.

Undelete a project

When you undelete a project, you get an option to update the name and description of the project. When the deletion is revoked, the project URLs will change if a different name of the deleted project is specified.

  1. For the deleted project you want to undelete, click Update Project Actions and select Undelete.

  2. In the Undelete Project dialog, if necessary, update the project name in Name, and update the description in Description.

    You would have to change the project name if another project with the same name was created after this project was deleted.

  3. Click Undelete.

Select multiple projects

You can select multiple projects and perform a common action on them.

  1. If necessary, filter and sort the projects as desired.

  2. Press the Ctrl key or the Shift key and select project rows.

    To select all projects, click the check box to the left of the Name column header.

  3. Click Update Selected and select the desired action from the menu.

Some options, such as Undelete, are not available in the Update Selected menu.

View usage metrics of projects

Next to the Detailed Filterthe Filter icon, review the projects and the disk usage metrics of the organization.

For each project, the Disk Usage column shows the project's disk usage and its usage percentage with respect to the total disk usage of all projects. Click the number to open a pop-up with details of usage by each service in the project.

Manage Your Development Cycle

After setting up VB Studio and adding users to IDCS, you should learn and then guide your organization's members about the development cycle in VB Studio.

To find out more about VB Studio and its projects, see Get Started in Managing Your Development Process with Visual Builder Studio. Learn about how to create a project, administer a project, add users to it, create and manage issues and Agile boards, review source code with merge requests, create and manage build jobs and pipelines, and use other features of VB Studio.

Set Your User Preferences

You can set your preferences, including your display name, email address, gravatar, and email notifications, from the User Preferences page.

To get to this page, click the user avatar and select Preferences:

Update Your Display Name

By default, VB Studio displays your Oracle Cloud account name as your display name across all pages. If you want to change it, you can do so from the User Preference page’s Profile tab:

  1. On the User Preferences page, click the Profile tab.
  2. In First Name and Last Name, update your name.
    The name is saved when the focus moves out of the field.
  3. To the left of the User Preferences title, click Close Close to return to the last opened page.
Update Your Email Address

By default, VB Studio displays your Oracle Cloud email address across all pages and sends email notifications, such as merge request notifications and issue notifications, to this email address.

If you want VB Studio email notifications sent to another email address, you can change it on the User Preference page’s Profile tab:

  • If you’re using an email address as your Oracle Cloud login username, your original Oracle Cloud email address continues to be your login username even after you change your email address preference.

  • After you provide another email address, you’ll receive a verification email. It's important that you take the time to verify the new email address because, if you don't, you won't receive any VB Studio email notifications. You can, however, continue to use VB Studio.

Here's how to change the email address that email notifications will be sent to:

  1. On the User Preferences page, click the Profile tab.
  2. In the Email Address field, enter your new email address.
    The email address is saved when the focus moves out of the field.
  3. Click the Re-send email button.
  4. In the email that you receive, click the confirmation link to confirm the email address.
    After the verification, you’re redirected to the service page.
  5. Open the Profile tab again and verify that the Email Address field displays the Verified label.
  6. To the left of the User Preferences title, click Close Close to return to the last opened page.
Add Your Avatar Picture

VB Studio displays your Gravatar picture as the avatar picture. If you don’t have a picture set in Gravatar or don’t have a Gravatar account, VB Studio displays your initials instead of your avatar picture. To find out more about Gravatar, see https://gravatar.com/.

Here's how to create a Gravatar account and upload your Gravatar picture:
  1. Open http://en.gravatar.com/ in your browser.
  2. Click Create Your Own Gravatar.
  3. Follow the on-screen instructions, enter the required details, and sign up.
    Create your account with the same email address that you used to subscribe to Oracle Cloud.
  4. After activating your account, sign in to Gravatar.
  5. Upload the avatar picture to your Gravatar account.
The picture uploaded to your Gravatar account is automatically displayed as your avatar picture in VB Studio.
Configure Your Global Email Notifications

You can configure your preferences to receive email notifications when a component, such as an issue or a Git repository's branch that you’re subscribed to is updated. Your preferences apply to all projects in which you are a member. Note that you must respond to the verification email you'll receive if you want to receive VB Studio email notifications.

Here's how to set your preferences for email notifications.
  1. On the User Preferences page, click the Notifications tab.
  2. Select or deselect the Notify Me Of check boxes.

    Some check boxes are selected by default. For a selected component, its notifications from all projects of the organization where you’re a member are enabled. You must subscribe or set up a watch on the component to get notifications about its updates:

    Select this check box ... To receive email notifications about:

    Issue updates, attachments and comments

    Issues you’re assigned to, or you’re watching.

    Merge Request updates and comments

    Merge requests where you’re a reviewer, or you’re watching.

    New features, tips, and events

    New features, tips, and events from the VB Studio team.

    Service and system maintenance updates

    Service and system maintenance updates from the VB Studio team.

    Build activities

    Jobs you’re watching.

    SCM/Push Activities

    Git repository branches you’re watching.

    Wiki page updates and comments

    Wiki pages you’re watching.

    Project Updates

    User updates when you or a user is added to or removed from a project, or the project role is changed.

    Include my Own Updates

    Your own changes.

    If you don’t select the check box, you won’t receive email notifications for issues, merge requests, and Git updates that you initiated or created even though the Issues updates, attachments and comments, the Merge Request updates and comments, or the SCM/Push Activities check boxes are selected.

  3. To the left of the User Preferences title, click Close Close to return to the last opened page.
Upload Your Public SSH Key

Before you can connect to a Git repository using SSH, you must first generate a private-public RSA SSH key pair and upload the public key to VB Studio. If you use multiple computers to access Git repositories, you'll need to generate an SSH key pair from each computer and upload its public key.

Generate an SSH Key

To generate an RSA SSH key pair, you can use any SSH client, including the Git CLI.

These steps assume you’re using Git CLI to generate the SSH keys:
  1. Open the Git CLI.
  2. On the command prompt, enter ssh-keygen -t rsa.
    To generate a larger key, enter ssh-keygen -t rsa -b 4096. If you're using a macOS version 10.13.6 (or higher), enter ssh-keygen -m PEM -t rsa.
  3. When prompted, enter a file name for the key and press Enter.
    If you don’t want to specify a file name, leave the name blank and press Enter. By default, the key pair files are saved as id_rsa.pub and id_rsa in the .ssh sub-directory under the Git HOME directory. For example, on Windows, the files are saved in C:\Users\<USER_PROFILE>\.ssh\.
  4. Enter a passphrase and press Enter. If you don’t want to specify a passphrase, leave it blank and press Enter.
    When prompted to confirm the passphrase, enter the same passphrase. If you didn’t specify a passphrase earlier, leave it blank and press Enter.

By default, Git CLI access the C:\Users\<USER_PROFILE>\.ssh\ directory to locate the private key. If you are using another Git client, you may need to configure it to access the private SSH key. Check your Git client’s documentation to find out how to do that.

Add the Public SSH Key to Your VB Studio Account

After generating an SSH private-public key pair, add the public key to your User Preferences page’s Authentication tab.

  1. On the computer where you generated the SSH key pair, navigate to the directory where the public key is saved.
  2. Open the public key file in a text editor, select the contents, and copy them to the clipboard.
  3. In VB Studio, click the user avatar and select Preferences.
  4. Click the Authentication tab.
  5. Click Add Key.
  6. In the New SSH Key dialog box, enter a unique name and paste the SSH key that you copied in Step 2.
  7. Click Create.
  8. To the left of the User Preferences title, click Close Close to return to the last opened page.
See the News Banner

A banner with the latest news from the VB Studio team is displayed on the Organization and Project Home pages' header.

To navigate between news pages, click the navigation buttons. To expand or collapse the banner, use the Expand the Down arrow icon or Collapse the Up arrow icon icons. To close the banner, click Close the X icon.
If the banner isn't visible, here's how to enable it:
  1. On the User Preferences page, click the General tab.
  2. Select the Show News Banner on Organization and Project Home check box.