Project Configuration YAML File

Functions are blocks of code that run on demand without the need to manage any infrastructure. Develop on your local machine, test your code from the command line (using doctl), then deploy to a production namespace or App Platform — no servers required. Learn more about functions.


The project.yml file is a YAML configuration file in the root directory of a project which lets you define environment variables, parameters, and other properties for the project and the packages and functions within it.

The structure of the information in project.yml is aligned with the structure of the project. Using this structure, you can scope the properties you define in project.yml to one of three different levels:

  • Scoped to the project, which is the top-level collection of resources, including at least one package
  • Scoped to a package, which is a collection of functions
  • Scoped to individual functions, which are called actions in the configuration file.

Additionally, the build process for project.yml uses a simple templating syntax which supports including variables from local .env files or App Platform environment variables.

Properties

Parameters

Parameters are passed into function invocations alongside query or POST parameters from the HTTP request.

  • Scope: Projects, packages, and functions.

  • Valid values: Any structure that converts to valid JSON, including nested lists and objects.

This parameters example defines two parameters: param1, which has a single value, and param2, which is a list of two values:

parameters:
  param1: <value>
  param2: 
    - <value>
    - <value>

Environment

Environment values defined in the configuration are added as the environment variables of the process that runs the function.

  • Scope: Projects, packages, and functions.

  • Valid values: Must be a string.

You can statically define environment variables in the project.yml file, as in this example:

environment:
  env1: <value>
  env2: <value>

You can also template environment variables from an .env file in the project filesystem or from App Platform’s environment variable configuration.

Main

The main parameter defines the entry point for a function.

  • Scope: Functions.

  • Valid values: Must be a string.

packages:
  - name: <package-name>
    actions:
      - name: <action-name>
        main: <main-entry-point>

If you don’t specify a main for a function, the build process will try to detect the correct entry point.

Runtime

The runtime parameter specifies the runtime package used by the function.

  • Scope: Functions.

  • Valid values: Any supported runtime. You can use the value default in place of the runtime version (for example, go:default instead of go:1.15).

packages:
  - name: <package-name>
    actions:
      - name: <action-name>
        runtime: <runtime>

If you do not specify a runtime, the build process will try to detect it.

Limits

The limits parameter lets you override the function’s default limits for timeout time, memory allocation, and total log size.

  • Scope: Functions.

  • Valid fields and values: An object with at least one field.

    • Timeout time uses the timeout field with a value in milliseconds.
    • Memory allocation uses the memory field with a value in megabytes.
    • Total log size uses the the logs field with a value in kilobytes.
packages:
- name: <package-name>
  actions:
    - name: <action-name>
      limits:
        timeout: <milliseconds>
        memory: <megabytes>
        logs: <kilobytes>

Templating

You can template variables in project.yml from local .env files or App Platform environment variables. This is especially useful in combination with App Platform’s encrypted variables for secret storage.

You can substitute in variables from the runtime environment using the format "${SYMBOL}", where SYMBOL is the name of the variable specified in App Platform. We recommend using quotes around the variable substitution to ensure proper parsing.

Examples

Basic

Here is a simplified example of a project.yml file:

    
        
            
parameters: # project scope
    param1: value
environment:
    env1: value
packages:
  - name: package1
    parameters: # package scope
    environment:
    actions:
      - name: function1
        parameters: # function scope
        environment:
        limits: 
        runtime: 'nodejs:default'
        main: ''

        
    

This example defines a single package, package1, and a single function within it, function1, which uses the nodejs:default runtime. This example also defines one parameter, param1, and one environment variable, env1, at the package scope.

With Templating

The following simplified YAML example includes some templated variables:

    
        
            
environment:
  # ENV is statically defined as "production" in this example:
  ENV: production
packages:
  - name: store
    environment:
      # DATABASE_URL will be substituted to the DATABASE_URL_READ_ONLY value
      # defined in App Platform's environment variable configuration. 
      # NOTE: The receiving variable name does not need to match the name as
      # defined in the app / component config. This facilitates narrowly
      # scoped or overlapping values.
      DATABASE_URL: "${DATABASE_URL_READ_ONLY}"
    actions:
      - name: buy 
        environment:
          # PAYMENT_API_KEY will substitute the PAYMENT_API_KEY variable
          # from App Platform's runtime variable configuration.
          PAYMENT_API_KEY: "${PAYMENT_API_KEY}"
          # DATABASE_URL will be substituted with the DATABASE_URL_WRITE 
          # value defined in App Platform's environment variable config.
          DATABASE_URL: "${DATABASE_URL_WRITE}"

        
    

By default, the doctl serverless deploy command will look for an .env file in the same directory as the project.yml file. You can also add an --env <path to .env-formatted file> flag to specify an alternate file name and location anywhere on the filesystem.

Learn More

Create a GitHub repository with the correct project structure in order to deploy your functions to production.
Use and encrypt environment variables in App Platform.
Create and configure functions in App Platform. Functions are blocks of code that run on demand without the need to manage any infrastructure.