Project Descriptor

+++ title="project.toml" aliases=[ "/docs/reference/project-descriptor/" ] weight=1 +++

The project descriptor file allows app developers to provide configuration for apps, services, functions and buildpacks.

It should, by default, be named project.toml, though users can name it differently, and pass the filename to pack by calling

$ pack build --descriptor <project-descriptor path>

The schema is as follows:

• _ (table, optional)

  A configuration table for a project.

  • schema-version (string, optional)
    A version identifier for the schema of the _ table and structure of the project descriptor file. It is a string that follows the format of the Buildpack API Version. The schema is documented in the project descriptor specification and is presently 0.2.

  • id (string, optional)
    A machine readable identifier for the project. For example, com.example.myservice.

  • name (string, optional)
    A human readable identifier for the project. For example, My Example Service.

  • version (string, optional)
    The version of the project.

  • authors (string list, optional)
    The names and/or email addresses of the project authors.

  • documentation-url (string, optional)
    A link to the documentation for the project.

  • source-url (string, optional)
    A link to the source code of the project.

  • licenses (list, optional)
    A list of project licenses. Each must contain at least one of the following fields:

    • type (string, optional)
      The type of license.

    • uri (string, optional)
      If the project uses a nonstandard license, you may use uri to point to the license.

• io.buildpacks (table, optional)

  A list of specifications for build-time configuration of the project.

  • build.env (list, optional) You can set environment variables at build time, by defining each with the following fields:

    • name (string, optional)
      The name of the environment variable

    • value (string, optional, default: latest)
      The assigned version of the environment variable

  • builder (string, optional)
    The builder image to use for the build.

  • include (string list, optional)
    A list of files to include in the build, while excluding everything else.

    OR

  • exclude (string list, optional)
    A list of files to exclude from the build, while including everything else.

  If include and exclude are both present, the lifecycle will error out.

  • group (list, optional) A list of buildpacks. Either a version, uri, or script table must be included, but it must not include any combination of these elements.

    • id (string, optional)
      An identifier for the buildpack. Must match ID specified in buildpack's buildpack.toml file.

    • version (string, optional, default: latest)
      The version of the buildpack. Must match version specified in buildpack's buildpack.toml file.

    • uri (string, default=urn:buildpack:<id>)
      A URL or path to an archive, a packaged buildpack (saved as a .cnb file), or a directory. If path is relative, it must be relative to the project.toml.

    • script (list, optional) Defines an inline buildpack.

      • api (string, required, current: 0.5)
        The Buildpack API version the buildpack adheres to. Used to ensure compatibility against the lifecycle.

      • inline (string, required)
        The build script contents.

      • shell (string, optional, default=/bin/sh)
        The shell used to execute the inline script.

• metadata (table, optional)

  Buildpacks and specific platforms are free to define additional arbitrary key-value pairs in the metadata table.

Example

An example project.toml is:

[_]
schema-version = "0.2"
id = "io.buildpacks.my-app"
version = "0.1"

[io.buildpacks]
include = [
    "cmd/",
    "go.mod",
    "go.sum",
    "*.go"
]

[[io.buildpacks.build.env]]
name = "JAVA_OPTS"
value = "-Xmx1g"

[[io.buildpacks.group]]
id = "io.buildpacks/java"
version = "1.0"

[[io.buildpacks.group]]
id = "io.buildpacks/nodejs"
version = "1.0"

[_.metadata]
foo = "bar"

[_.metadata.fizz]
buzz = ["a", "b", "c"]

Specification

For more detail, you can check out the project.toml specification