<commit_before>##### POST `/v2/apps`

Create and start a new application.

Here is an example of an application JSON which includes all fields. 

```javascript
{
    "id": "/product/service/myApp",
    "cmd": "env && sleep 300",
    "args": ["/bin/sh", "-c", "env && sleep 300"]
    "cpus": 1.5,
    "mem": 256.0,
    "ports": [
        8080,
        9000
    ],
    "requirePorts": false,
    "instances": 3,
    "executor": "",
    "container": {
        "type": "DOCKER",
        "docker": {
            "image": "group/image",
            "network": "BRIDGE",
            "portMappings": [
                {
                    "containerPort": 8080,
                    "hostPort": 0,
                    "servicePort": 9000,
                    "protocol": "tcp"
                },
                {
                    "containerPort": 161,
                    "hostPort": 0,
                    "protocol": "udp"
                }
            ],
            "privileged": false,
            "parameters": [
                { "key": "a-docker-option", "value": "xxx" },
                { "key": "b-docker-option", "value": "yyy" }
            ]
        },
        "volumes": [
            {
                "containerPath": "/etc/a",
                "hostPath": "/var/data/a",
                "mode": "RO"
            },
            {
                "containerPath": "/etc/b",
                "hostPath": "/var/data/b",
                "mode": "RW"
            }
        ]
    },
    "env": {
        "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
    },
    "constraints": [
        ["attribute", "OPERATOR", "value"]
    ],
    "acceptedResourceRoles": [ /* since 0.9.0 */
        "role1", "*"
    ],
    "labels": {
        "environment": "staging"
    },
    "uris": [
        "https://raw.github.com/mesosphere/marathon/master/README.md"
    ],
    "dependencies": ["/product/db/mongo", "/product/db", "../../db"],
    "healthChecks": [
        {
            "protocol": "HTTP",
            "path": "/health",
            "gracePeriodSeconds": 3,
            "intervalSeconds": 10,
            "portIndex": 0,
            "timeoutSeconds": 10,
            "maxConsecutiveFailures": 3
        },
        {
            "protocol": "TCP",
            "gracePeriodSeconds": 3,
            "intervalSeconds": 5,
            "portIndex": 1,
            "timeoutSeconds": 5,
            "maxConsecutiveFailures": 3
        },
        {
            "protocol": "COMMAND",
            "command": { "value": "curl -f -X GET http://$HOST:$PORT0/health" },
            "maxConsecutiveFailures": 3
        }
    ],
    "backoffSeconds": 1,
    "backoffFactor": 1.15,
    "maxLaunchDelaySeconds": 3600,
    "upgradeStrategy": {
        "minimumHealthCapacity": 0.5,
        "maximumOverCapacity": 0.2
    }
}
```

##### id (String) 

Unique identifier for the app consisting of a series of names separated by slashes.
Each name must be at least 1 character and may
only contain digits (`0-9`), dashes (`-`), dots (`.`), and lowercase letters
(`a-z`). The name may not begin or end with a dash.

The allowable format is represented by the following regular expression 
`^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$`

##### cmd (String)

The command that is executed.  This value is wrapped by Mesos via `/bin/sh -c ${app.cmd}`.  Either `cmd` or `args` must be supplied. It is invalid to supply both `cmd` and `args` in the same app.

##### args (Array of Strings)

An array of strings that represents an alternative mode of specifying the command to run. This was motivated by safe usage of containerizer features like a custom Docker ENTRYPOINT. This args field may be used in place of cmd even when using the default command executor. This change mirrors API and semantics changes in the Mesos CommandInfo protobuf message starting with version `0.20.0`.  Either `cmd` or `args` must be supplied. It is invalid to supply both `cmd` and `args` in the same app.

##### cpus (Float)

The number of CPU`s this application needs per instance. This number does not have to be integer, but can be a fraction.

##### mem (Float)

The amount of memory in MB that is needed for the application per instance. 

##### ports (Array of Integers)

An array of required port resources on the host.

The port array currently serves multiple roles:

* The number of items in the array determines how many dynamic ports are allocated
  for every task.
* For every port that is zero, a globally unique (cluster-wide) port is assigned and
  provided as part of the app definition to be used in load balancing definitions.
  See [Service Discovery Load Balancing doc page]({{ site.baseurl }}/docs/service-discovery-load-balancing.html)
  for details.

Since this is confusing, we recommend to configure ports assignment for docker
containers in `container.docker.portMappings` instead, see
[Docker Containers doc page]({{ site.baseurl }}/docs/native-docker.html#bridged-networking-mode)).

Alternatively or if you use the Mesos Containerizer, pass zeros as port values to generate one or more arbitrary
free ports for each application instance.
Each port value is exposed to the instance via environment variables
`$PORT0`, `$PORT1`, etc. Ports assigned to running instances are also available
via the task resource.

We will probably provide an alternative way to configure this for non-docker apps in the future
as well, see [Rethink ports API](https://github.com/mesosphere/marathon/issues/670).

##### requirePorts (Boolean)

Normally, the host ports of your tasks are automatically assigned. This corresponds to the
`requirePorts` value `false` which is the default.

If you need more control and want to specify your host ports in advance, you can
 set `requirePorts` to `true`. This way the ports you have specified are used as host ports. That also
 means that Marathon can schedule the associated tasks only on hosts that have the specified ports available.

 The specified ports need to be in the local port range specified by the
 `--local_port_min` and `--local_port_max` flags. See
 [Command Line Flags doc page]({{ site.baseurl }}/docs/command-line-flags.html)).

##### instances (Integer)

The number of instances of this application to start. Please note: this number can be changed everytime as needed to scale the application.

##### executor (String)

The executor to use to launch this application. Different executors are available. The simplest one (and the default if none is given) is //cmd, which takes the cmd and executes that on the shell level.

##### container (Object)

Additional data passed to the containerizer on application launch.  These
consist of a type, zero or more volumes, and additional type-specific options.
Volumes and type are optional (the default type is DOCKER).  In order to make
use of the docker containerizer, specify `--containerizers=docker,mesos` to
the Mesos slave.  For a discussion of docker-specific options, see the
[native docker document]({{site.baseurl}}/docs/native-docker.html).

##### env (Object with String values)
 
Key value pairs that get added to the environment variables of the process to start.

##### constraints

Valid constraint operators are one of ["UNIQUE", "CLUSTER",
"GROUP_BY"]. For additional information on using placement constraints see
the [Constraints doc page]({{ site.baseurl }}/docs/constraints.html).
<commit_msg>Improves #2091 - Remove incorrect statement from the docs<commit_after>##### POST `/v2/apps`

Create and start a new application.

Here is an example of an application JSON which includes all fields. 

```javascript
{
    "id": "/product/service/myApp",
    "cmd": "env && sleep 300",
    "args": ["/bin/sh", "-c", "env && sleep 300"]
    "cpus": 1.5,
    "mem": 256.0,
    "ports": [
        8080,
        9000
    ],
    "requirePorts": false,
    "instances": 3,
    "executor": "",
    "container": {
        "type": "DOCKER",
        "docker": {
            "image": "group/image",
            "network": "BRIDGE",
            "portMappings": [
                {
                    "containerPort": 8080,
                    "hostPort": 0,
                    "servicePort": 9000,
                    "protocol": "tcp"
                },
                {
                    "containerPort": 161,
                    "hostPort": 0,
                    "protocol": "udp"
                }
            ],
            "privileged": false,
            "parameters": [
                { "key": "a-docker-option", "value": "xxx" },
                { "key": "b-docker-option", "value": "yyy" }
            ]
        },
        "volumes": [
            {
                "containerPath": "/etc/a",
                "hostPath": "/var/data/a",
                "mode": "RO"
            },
            {
                "containerPath": "/etc/b",
                "hostPath": "/var/data/b",
                "mode": "RW"
            }
        ]
    },
    "env": {
        "LD_LIBRARY_PATH": "/usr/local/lib/myLib"
    },
    "constraints": [
        ["attribute", "OPERATOR", "value"]
    ],
    "acceptedResourceRoles": [ /* since 0.9.0 */
        "role1", "*"
    ],
    "labels": {
        "environment": "staging"
    },
    "uris": [
        "https://raw.github.com/mesosphere/marathon/master/README.md"
    ],
    "dependencies": ["/product/db/mongo", "/product/db", "../../db"],
    "healthChecks": [
        {
            "protocol": "HTTP",
            "path": "/health",
            "gracePeriodSeconds": 3,
            "intervalSeconds": 10,
            "portIndex": 0,
            "timeoutSeconds": 10,
            "maxConsecutiveFailures": 3
        },
        {
            "protocol": "TCP",
            "gracePeriodSeconds": 3,
            "intervalSeconds": 5,
            "portIndex": 1,
            "timeoutSeconds": 5,
            "maxConsecutiveFailures": 3
        },
        {
            "protocol": "COMMAND",
            "command": { "value": "curl -f -X GET http://$HOST:$PORT0/health" },
            "maxConsecutiveFailures": 3
        }
    ],
    "backoffSeconds": 1,
    "backoffFactor": 1.15,
    "maxLaunchDelaySeconds": 3600,
    "upgradeStrategy": {
        "minimumHealthCapacity": 0.5,
        "maximumOverCapacity": 0.2
    }
}
```

##### id (String) 

Unique identifier for the app consisting of a series of names separated by slashes.
Each name must be at least 1 character and may
only contain digits (`0-9`), dashes (`-`), dots (`.`), and lowercase letters
(`a-z`). The name may not begin or end with a dash.

The allowable format is represented by the following regular expression 
`^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$`

##### cmd (String)

The command that is executed.  This value is wrapped by Mesos via `/bin/sh -c ${app.cmd}`.  Either `cmd` or `args` must be supplied. It is invalid to supply both `cmd` and `args` in the same app.

##### args (Array of Strings)

An array of strings that represents an alternative mode of specifying the command to run. This was motivated by safe usage of containerizer features like a custom Docker ENTRYPOINT. This args field may be used in place of cmd even when using the default command executor. This change mirrors API and semantics changes in the Mesos CommandInfo protobuf message starting with version `0.20.0`.  Either `cmd` or `args` must be supplied. It is invalid to supply both `cmd` and `args` in the same app.

##### cpus (Float)

The number of CPU`s this application needs per instance. This number does not have to be integer, but can be a fraction.

##### mem (Float)

The amount of memory in MB that is needed for the application per instance. 

##### ports (Array of Integers)

An array of required port resources on the host.

The port array currently serves multiple roles:

* The number of items in the array determines how many dynamic ports are allocated
  for every task.
* For every port that is zero, a globally unique (cluster-wide) port is assigned and
  provided as part of the app definition to be used in load balancing definitions.
  See [Service Discovery Load Balancing doc page]({{ site.baseurl }}/docs/service-discovery-load-balancing.html)
  for details.

Since this is confusing, we recommend to configure ports assignment for docker
containers in `container.docker.portMappings` instead, see
[Docker Containers doc page]({{ site.baseurl }}/docs/native-docker.html#bridged-networking-mode)).

Alternatively or if you use the Mesos Containerizer, pass zeros as port values to generate one or more arbitrary
free ports for each application instance.
Each port value is exposed to the instance via environment variables
`$PORT0`, `$PORT1`, etc. Ports assigned to running instances are also available
via the task resource.

We will probably provide an alternative way to configure this for non-docker apps in the future
as well, see [Rethink ports API](https://github.com/mesosphere/marathon/issues/670).

##### requirePorts (Boolean)

Normally, the host ports of your tasks are automatically assigned. This corresponds to the
`requirePorts` value `false` which is the default.

If you need more control and want to specify your host ports in advance, you can
 set `requirePorts` to `true`. This way the ports you have specified are used as host ports. That also
 means that Marathon can schedule the associated tasks only on hosts that have the specified ports available.

##### instances (Integer)

The number of instances of this application to start. Please note: this number can be changed everytime as needed to scale the application.

##### executor (String)

The executor to use to launch this application. Different executors are available. The simplest one (and the default if none is given) is //cmd, which takes the cmd and executes that on the shell level.

##### container (Object)

Additional data passed to the containerizer on application launch.  These
consist of a type, zero or more volumes, and additional type-specific options.
Volumes and type are optional (the default type is DOCKER).  In order to make
use of the docker containerizer, specify `--containerizers=docker,mesos` to
the Mesos slave.  For a discussion of docker-specific options, see the
[native docker document]({{site.baseurl}}/docs/native-docker.html).

##### env (Object with String values)
 
Key value pairs that get added to the environment variables of the process to start.

##### constraints

Valid constraint operators are one of ["UNIQUE", "CLUSTER",
"GROUP_BY"]. For additional information on using placement constraints see
the [Constraints doc page]({{ site.baseurl }}/docs/constraints.html).

{'fraction_non_alphanumeric': 0.11788341051484609, 'fraction_numerical': 0.012939253609370744, 'mean_word_length': 2.555690072639225, 'pattern_counts': {'":': 134, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1464062', 'n_tokens_mistral': 4302, 'n_tokens_neox': 4020, 'n_words': 1623}