Creating Metadata Files

You can specify deployment information, such as the launch command, the number of application instances to create, and service bindings, in one or two metadata files that you upload with your application.

When you upload your application to Oracle Application Container Cloud Service using the user interface, you must include a file called manifest.json if your application requires a launch command. This file can be included at the root of the archive or specified separately.

The other file, deployment.json, is optional and is not included in the archive. You can specify the values in this file via the user interface, or you can upload the file using the REST API.

The manifest.json File

The manifest.json file specifies how to launch your application. Optionally, you can include the runtime version and other parameters.

manifest.json Syntax

Syntax

  • runtime

    • majorVersion – (Optional) Major version of the runtime environment. Each language has its own numbering system.

      For Java SE, use 7, 8, or 9. For Java EE, use 7. For Node, use 0.10 , 0.12, 4, 6, or 8. For PHP, use 5.6, 7.0, or 7.1. For Python, use 2.7.13 or 3.6.0. For Ruby, use 2.3.4 or 2.4.1. For Go, use 1.7.6 or 1.8.3.

  • type – (Optional) Determines whether an application is public or private:

    • web (the default) – Specifies a public application, which you can access using a public URL, the public REST API, or the command-line interface.

    • worker – Specifies a worker application, which is private and runs in the background. The isClustered parameter should be set to true in some cases. See Preparing a Worker Application for Deployment.

  • command  – (Required except for Java EE and PHP) Launch command to execute after the application has been uploaded.

    Most PHP applications don’t need a launch command. Unless another file is specified in the application URL, the index file opens first, whether the extension is .htm, .html, or .php. See Selecting the Launch Command.

    For a Java EE web application, the launch command, if present, is ignored.
  • startupTime – (Optional) Maximum time in seconds to wait for the application to start. Allowed values are between 10 and 600. The default is 30. If the application doesn’t start in the time specified, the application is deemed to have failed to start and is terminated. For example, if your application takes two minutes to start, set startupTime to at least 120.

  • shutdownTime – (Optional) Maximum time in seconds to wait for the application to stop. Allowed values are between 0 and 600. The default is 0. This allows the application to close connections and free up resources gracefully. For example, if your application takes two minutes to shut down, set shutdownTime to at least 120.

  • release – (Optional)

    • build – User-specified value of build.

    • commit – User-specified value of commit.

    • version – User-specified application version.

  • notes – (Optional) Comments.

  • mode – (Optional) Restart mode for application instances when the application is restarted. The only allowed option is rolling for a rolling restart. Omit this parameter to be prompted for a rolling or concurrent restart. See Stopping, Starting, and Restarting an Application in Using Oracle Application Container Cloud Service.

  • isClustered – (Optional) Must be set to true for application instances to act as a cluster, with failover capability. See Preparing a Clustered Application for Deployment.

Example 4-1 Sample manifest.json for a Java application

{
    "runtime": {
        "majorVersion": "7"
    },
    "type": "web",
    "command": "java -jar myapp.jar",
    "startupTime": "120",
    "release": {
        "build": "150520.1154",
        "commit": "d8c2596364d9584050461",
        "version": "15.1.0"
    },
    "notes": "notes related to release",
    "mode": "rolling"
}

Example 4-2 Sample manifest.json for a Node application

{
  "runtime":{
     "majorVersion":"0.12"
},
  "command": "node server.js",
  "mode": "rolling"
}

Example 4-3 Sample manifest.json for a PHP application

{
  "runtime":{
     "majorVersion":"5.6"
},
  "command": "sh app.sh",
  "notes": "This PHP app is launched from a script",
  "mode": "rolling"
}

Example 4-4 Sample manifest.json for a Python application

{
  "runtime":{
     "majorVersion":"3.6.0"
},
  "command": "python app.py",
  "mode": "rolling"
}

Example 4-5 Sample manifest.json for a Ruby application

{
  "runtime":{
     "majorVersion":"2.4.1"
},
  "command": "ruby app.rb",
  "mode": "rolling"
}

Example 4-6 Sample manifest.json for a Go application

{
  "runtime":{
     "majorVersion":"1.8.3"
},
  "command": "go run app.go",
  "mode": "rolling"
}

The deployment.json File

This file is optional.

The deployment.json file specifies how much memory to allocate to the application, how many application instances to create initially, additional environment variables, and service bindings to other Oracle Cloud services. You can specify these same options from the user interface, or you can upload this file using the REST API. If no values are specified or the file is omitted, memory and instance defaults are used.

When a service binding is created, its environment variables are automatically created. For example, for Oracle Database Cloud Service, these variables have names beginning with DBAAS_. See Configuring Environment Variables in Using Oracle Application Container Cloud Service.

deployment.json Syntax

  • memory – The amount of memory in gigabytes made available to the application. Values range from 1G to 20G. The default is 2G.

  • instances – Number of application instances. The default is 2. The maximum is 64.

  • notes – Free-form comment field. It can be used, for example, to describe the deployment plan.

  • environment  – Environment variables used by the application. This element can contain any number of name-value pairs.

    • name – Environment variable name.

    • value – Environment variable value.

  • java_system_properties  – Java EE system properties used by the application. This element can contain any number of name-value pairs.

    • name – Property name.

    • value – Property value.

  • services  – Service bindings for connections to other Oracle Cloud services. This element can contain more than one block of sub-elements. Each block specifies one service binding.

    • identifier – User-specified identifier.

    • type – Type of the service: JAAS for Oracle Java Cloud Service, DBAAS for Oracle Database Cloud Service, MYSQLCS for MySQL Cloud Service, OEHCS for an Oracle Event Hub Cloud Service topic, OEHPCS for an Oracle Event Hub Cloud Service cluster, DHCS for Oracle Data Hub Cloud Service, or caching for a cache.

    • name – Name of the service, the name of an existing Oracle Java Cloud Service instance, Oracle Database Cloud Service database, MySQL Cloud Service database, Oracle Event Hub Cloud Service topic or cluster, Oracle Data Hub Cloud Service instance, or cache name.

    • username – Username used to access the service.

    • password – Password for the username.

Note:

The username and password are not automatically used to authenticate against the target service. The values are placed in the SERVICE_USER_NAME and SERVICE_USER_PASSWORD environment variables, which your application can access. If the target service requires authentication, your application must handle it. If the target service doesn’t require authentication, you can’t omit the username and password from the services element, but you can specify any values.

Note:

If you download a deployment.json file from a deployed application that has a service binding, you see an additional id element under services. The value of this element is system-generated. For a new application, do not upload a deployment.json file that includes this element. For an existing application, do not change the value of this element.

Example 4-7 deployment.json Example

{
    "memory": "2G",
    "instances": "2",  
    "environment": {
        "NO_OF_CONNECTIONS":"25",
        "TWITTER_ID":"JAVA"
    },
    "services": [{
        "identifier": "ProdService",
        "type": "JAAS",
        "name": "Jaas Service",
        "username": "username",
        "password": "password"
    },
    {
        "identifier": "DBService",
        "type": "DBAAS",
        "name": "MyDB",
        "username": "username",
        "password": "password"
    }]
}