Publishing Guidelines

Mandatory Guidelines

The following guidelines are mandatory for application listings in Oracle Cloud Infrastructure Marketplace. Each guideline must be followed. Before being approved, each application listing is validated against each of these guidelines.

• The App Name must be 80 characters or less. It should be 36 characters or less for optimal viewing.
• The App Name must be clear, concise, and free of spelling and grammar mistakes. It must have no line breaks.
• The Headline must clearly state the application's purpose. It must be described in two lines or less and be free of spelling and grammar mistakes.
• Font/Spacing on the listing must be consistent.
• All text must be free of spelling or grammar errors.
• The Description must be comprehensive and capture the target audience/type of user and present why the Listing is valuable.
• All links must point to the correct locations and open in a new tab or window.
• Text included in icons, banners, screenshots or videos must be legible.
• Images must not be blurred or stretched.
• Related Documents must provide consistent information for users to be able to:
  1. Launch an instance from Marketplace.
  2. Connect to the instance.
  3. Setup or start the application.
• The Support section must contain accurate contact details for customer to engage partner support. These contact details must contain an accurate phone number or email address.
• The System Requirements must contain the list of required Oracle Cloud Infrastructure components including compute shapes, security rules, IAM policies, block volumes, secondary VNICs, etc.
• Terms of Use must be included in your app install package and be free of spelling or grammar errors. Terms of Use name must be in title case. Links in Terms of Use must point to the correct locations and open in a new tab or window.
• The app install package version must match the version specified in any other related image or text for this package.
• The user must be able to launch, connect, and configure the application and related infrastructure using instructions included in the Usage and Related Documents sections.
• Each published solution includes a set of customer facing documentation. This documentation:
  • Must include prominent, detailed instructions for connecting to an instance.
  • Must include usage documentation or a link to the documentation.
  • Must include support details or a link to those details.
  • Must list compatible shapes.
  • Must document all network ports open by default on the instance.
• Acknowledgment: You agree that you shall not publish any paid Publisher listings on the Oracle Cloud Marketplace if the purchase of products and services and/or provision of related services to the customer may be funded in whole or in part by medicare, medicaid, or any other federal or state funded healthcare program.

Recommended Guidelines

The following guidelines can be considered as best practices that should be followed whenever possible.

• The release notes should be specified as bullet points with proper line breaks.
• The related documents should contain information on how to purchase a license if necessary.

General Guidelines

Here are some generic guidelines for listings of all types. For guidelines specific to application listings or image listings, see the relevant section.

• To ensure the listing content adapts correctly to the Oracle Cloud Marketplace cross platform styling, only basic formatting is allowed in the description sections. If the content is being copied from another rich text source (such as Microsoft Word), ensure any additional styling is removed before submitting the listing for review.
• Pasting content in plain text is recommended to avoid including any hidden styles and formatting. Adhering to these basic formatting options will ensure the listing content displays correctly across multiple devices and platforms.
• The use of the Oracle trademarks within the listing content (such as Oracle product names) must conform to the Third Party Usage Guidelines for Oracle Trademarks.
• The use of the Oracle logos within the listing content (such as infographics and screenshots) must conform to the Third Party Usage Guidelines for Oracle Logos.
• For any images such as logos, icons, or banners:
  • Ensure that the images are sized to match the specified dimensions.
  • Save images in the specified file format with compression.
  • Ensure that the image file size is within the specified file size.
  • Your banner must be 1160 pixels (width) by 200 pixels (height), a maximum of 10 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file.
  • Your company logo must be 115 pixels by 115 pixels, a maximum of 5 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file..
  • Your icon must be 130 pixels by 130 pixels, a maximum of 5 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file.
  • Application icons should be distinctive and unique. Don’t submit multiple applications with the same icon.
  • Don’t use any Oracle logos or trademarks in the application icons. Ensure you have the usage rights to any third party images used.
• The content of the description section should provide a high-level overview of the application. It must describe the value and benefit to the customer of running/hosting the application on the Oracle Cloud.
• A long description must be preceded by a short description. Don’t repeat the short description in the long description section.
• The description should not highlight or refer to “Oracle Validated Integration”. The Oracle Validated Integration (OVI) program is only applicable to on-premises solutions, and does not apply to the Oracle Cloud.
• In the Usage Information field:
  • Include a link to a Getting Started guide that contains complete details required by users to get started.
  • Include links to any technical documentation, data-sheets, user guides, and other related documents (including the ones you specify in the Related Documents section).
  • List the ports that must be opened. Add a link such as "How to configure open ports" which describes the steps to open ports using the Oracle Cloud Infrastructure Console.
• In the Screenshots and Videos field, for screenshots:
  • A minimum of two screenshots is recommended.
  • When taking screenshots, hide any browser tool bars and menus. Use the browser full-screen mode.
  • The recommended dimensions for screenshots is 640 pixels (width) x 480 pixels (height). Other suitable sizes include 1024x768 and 1200x900. Larger images should be cropped or resized.
  • For best results, images should be created with a native 4:3 aspect ratio. For any images that don’t fit the 4:3 aspect ratio, such as screenshots of mobile phone apps, pad the image with an appropriately colored or transparent background to fit the required image size. Use an image editor to add padding.
  • Screenshots must be a maximum of 5 MB, and must be a BMP, GIF, JPEG (JPG), or PNG file.
  • Uploaded images are automatically scaled to 240 x 180 pixels thumbnails on the main listing page.
  • Uploaded images are automatically scaled to fit the 600 x 450 pixels media viewer.
  For videos:
  • Include a demonstration video as the first item in the list in the Screenshots and Videos field.
  • Promotional videos that are hosted on YouTube or Vimeo can be embedded directly in the screenshot list and media viewer.
  • The URL address for the video must start with either http:// or https://
  • The main demo video should be short and to the point, focusing on the main features of the application and the value of the application/integration on the Oracle Cloud.
  • Longer videos and promotional content can be included as additional videos.
• In the Related Documents field:
  • Addition of a data sheet specific to the Oracle Cloud integration is a minimum requirement.
  • Data sheets should be specific to the Oracle Cloud enabled release of the application.
  • Add a "Getting Started with Oracle Cloud Infrastructure" document that provides complete details for customers to configure and setup the software.
• In the System Requirements field:
  • List any Oracle Cloud PaaS services required to install and run the application.
  • List all Oracle Cloud SaaS services that the application is integrated with.
  • List any third party system dependencies.
  • Include browser-specific dependencies or supported mobile platforms in this section.
  • Be specific about any version or edition dependencies, or sizing requirements (if required).

Mandatory Guidelines for Linux Images

The following table lists the mandatory image guidelines and corresponding error code. Each guideline must be followed. Before an image is published to Oracle Cloud Infrastructure Marketplace, each image is validated against each of the following mandatory guidelines.

Mandatory Guidelines for Windows Images

Recommended Guidelines for Linux Images

The following guidelines are recommended for images listed in Oracle Cloud Infrastructure Marketplace. Each guideline is considered a best practice that should be followed if possible.

PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

Mandatory Guidelines

The following are mandatory guidelines for stacks listed in Oracle Cloud Infrastructure Marketplace. Each guideline must be followed. Before being published, each stack artifact is validated against each of these guidelines.

1. Stack artifact must be a zip file including the Terraform configuration file(s) and a Schema file.
   • Zip must include at least one configuration file (.tf) in the root folder.
   • Zip must include the Schema file (.yaml) in the root folder.
   • Zip must not include a Terraform state file in the zip file. State files are managed by Oracle Resource Manager (ORM). When customers launch a stack, ORM creates and manages the resources and the state file become available for download only.
   • Zip must not include Terraform runtime configuration folder (.terraform).
2. Terraform configuration must only use instance image(s) that are Approved or Published (Public or Private) Marketplace Image(s). It must have a Marketplace subscription to each of these image(s). It must have hard-coded reference(s) to these Marketplace Image(s). See Sample Terraform Configuration for a Marketplace Image Subscription and Usage for more details.
3. Binaries must not be downloaded from external repositories. All binaries and dependencies must be baked into the published Marketplace Image.
4. The Terraform remote exec provisioner must only be run within the Oracle Cloud Infrastructure domain. It must not download files on a remote server.
5. Third-party code or binaries must not be downloaded using cloud-init.
   1. cloud-init is a commonly used startup configuration utility for cloud compute instances. It accepts configuration via user-data mechanisms specified as part of the metadata definition on oci_core_instance resource.
   2. There are multiple user-data formats supported by cloud-init. See https://cloudinit.readthedocs.io/en/latest/topics/format.html.
   3. Regardless of the user-data format, cloud-init MUST NOT be used for downloading any third-party code or binary. All binaries required during the instance launch process (bootstrap), if not available within the image, should be downloaded by a process (script) baked as part of the image distribution, not injected via cloud-init (for example, leveraging wget).
   4. However, you may have a cloud-init template set up for customers to use in some particular scenarios, for example, to import a license key file, or to import a configuration file. In that case, you should provide a variable in the Terraform template code to enable customers to enter some data into the cloud-init building block, for example, leveraging Terraform template_file data source.
6. The Terraform provider must be Oracle Cloud Infrastructure. Other cloud providers or third-party application providers are not supported.
7. If a Terraform module is used, it must be loaded from local relative paths. It cannot be loaded from a remote repository.
8. The Terraform configuration must use instance principal authentication.

9. You must specify the minimum and maximum supported Terraform versions on which you have tested your stack.

   • Specify the minimum required Terraform version in the format: ~> <major_version>.<minor_version>.<patch_version>.

     Where, the patch_version is always set to 0. When a stack is launched, Resource Manager checks the <major_version>.<minor_version> that you have defined in your code and uses the most recent patch version available. That's why you must use the ~> sign instead of the => sign while specifying the minimum required Terraform version.

     For example, ~> 0.14.0 indicates the supported Terraform versions are 0.14.0 or later.

   • Specify the maximum required Terraform version in the format: < <major_version>.<minor_version>.

     For example, < 0.15 indicates that the supported Terraform versions are earlier than 0.15.

   The following example shows how to specify the minimum and maximum supported Terraform versions when you have tested your stack only on Terraform 0.14.

   terraform 
   { required_version = "~> 0.14.0, < 0.15" }

For more information about Terraform, including the Oracle Cloud Infrastructure provider, instance principal authentication, and the remote exec provisioner, see the Terraform documentation for Provider Configuration. For information about supported versions of Terraform, see Getting Started with the Terraform Providerin Oracle Cloud Infrastructure Documentation.

Coding Guidelines for Terraform Configurations

The following guidelines are recommended for stacks listed in Oracle Cloud Infrastructure Marketplace. Each guideline is considered a best practice that should be followed if possible.

• Stack artifact should enable customers to either create all the infrastructure resources or point to existing ones (network, storage, and so on).
• Naming conventions and formatting should be followed:
  • Casing - Use lower_snake_case for all naming. This applies to variable names, resource names, module names, file names, display names, and so on.
  • Specifying Resource Type - Do not include the resource or data source type in the name. In Terraform, resources and data sources are always referenced by <type>.<name>. As such, there is no need to include the type in the name itself.
  • ID vs OCID - In Oracle Cloud Infrastructure, id generally refers to a field that takes an OCID. As such, variables should use id when referring to OCID values, instead of using ocid.
  • Variable Names - Variable names for Oracle Cloud Infrastructure resources should typically use the same name as used for the Terraform resource.
  • Display Names - Display names for Oracle Cloud Infrastructure resources should typically use the same name as used for the Terraform resource.
  • Naming module variables and outputs - When using a module, the naming of the input (variables) and the outputs should be exposed to the caller.
  • terraform fmt should be applied to all Terraform before checking it in.