fastly.toml package manifest format

Fastly services provide execution environments for your custom edge code. In the case of VCL services, you can upload VCL source code, which is compiled on the Fastly platform. However, Compute@Edge services are compiled in your own environment using the Fastly CLI, and the resulting binary is uploaded to the Fastly platform.

Compute@Edge packages are configured using a fastly.toml file in the root of the package directory tree. This file specifies configuration metadata related to a variety of tasks:

attribution of the package (e.g., name, author)
information required by the fastly CLI to compile and upload it to a compatible Fastly service
configuration of local server environments
bootstrapping of service configuration

In general, you should not write a fastly.toml file yourself. Instead, create a new Compute@Edge project using the fastly CLI by executing:

$ fastly compute init

This will walk you through the creation of the project and will write the fastly.toml file for you.

Example

The following is an example of a fastly.toml file for a project built using our Rust SDK:

fastly.toml

TOML

1manifest_version = 2
2name = "my-compute-project"
3description = "A wonderful Compute@Edge project that adds edge computing goodness to my application architecture."
4authors = ["me@example.com"]
5language = "rust"
6service_id = "SU1Z0isxPaozGVKXdv0eY"
7
8[scripts]
9build = "cargo build --bin fastly-compute-project --release --target wasm32-wasi --color always"

Reference

The syntax of fastly.toml is the TOML format.

The TOML format supports comments. A line that begins with a # character is ignored:

# This is a comment.

Property names and values are separated by =. The following properties are defined for fastly.toml files (refer to the TOML specification to understand the 'Types' mentioned below):

Property name	Type	Description
`manifest_version`	Number	Package manifest schema version number. Currently at version `2`. Any breaking changes to the manifest format should be accompanied by a change to the manifest version and the format changes will be documented here.
`name`	String	Name of the package. If there is no `service_id` specified in the same manifest, a new service will be created and this will become the name of the service as well as the name of the uploaded package. If the project is deployed to an existing service, any change to the `name` will update the name of the compute package, but will not change the name of the service.
`authors`	Array: string	An array of strings, listing email addresses of the authors of the project, for audit purposes. Displayed in the web interface and reported back via the API.
`description`	String	Brief description of the project, for audit purposes. Displayed in the web interface and reported back via the API.
`language`	String	Language used for the project. Either `"rust"`, `"assemblyscript"`, or another language SDK supported by Compute@Edge. This determines how the `fastly` CLI will compile your project to WebAssembly before it is uploaded to the Fastly edge cloud.
`profile`	String	Name of the profile account the Fastly CLI should use to make API requests. The profile consists of a token and email that is associated with a profile 'name'.
`service_id`	String	The Fastly service ID of the service to which the `fastly` CLI should deploy the package. If not specified, a new service will be created when the project is deployed.
`setup`	Table	Describes a set of service configuration that works with the code in the package. See setup information below. Ignored if `service_id` is present.
`scripts`	Table	Customisation options for the Fastly CLI build step. See Scripts below.
`└─ build`	String	Custom shell command to produce a Wasm binary (the output path should be `bin/main.wasm`).
`└─ post_build`	String	Custom shell command to run after the build step in the Fastly CLI.
`local_server`	Table	Describes the configuration for the local server built into the Fastly CLI, which can be invoked with `fastly compute serve`. See local server below.

Scripts

The [scripts] section of the fastly.toml file specifies how to define a build step, and 'post build' step, that integrates with the Fastly CLI.

The build property must produce a bin/main.wasm binary. From version v4.0.0 onwards, configuring the build property is required.

Here is an example for a project built using our JS SDK:

fastly.toml

TOML

[scripts]
build = "$(npm bin)/webpack && $(npm bin)/js-compute-runtime ./bin/index.js ./bin/main.wasm"

Webpack bundles the project's ./src/index.js into a ./bin/index.js. js-compute-runtime then takes the bundled file and produces the required ./bin/main.wasm binary.

NOTE: Once js-compute-runtime supports spec-compliant import/export statements, the Fastly JS starter kits will no longer have a reliance on webpack.

The post_build is executed after the Wasm binary has been produced, but before it has been packaged into a .tar.gz archive file. This allows users to further optimise the produced Wasm binary to meet their requirements.

Here is an example of defining a post_build step for a project built using our Go SDK:

fastly.toml

TOML

[scripts]
build = "tinygo build -target=wasi -wasm-abi=generic -gc=conservative -o bin/main.wasm ./"
post_build = "wasm-strip bin/main.wasm"

Local server

The [local_server] section of the fastly.toml file specifies how fastly compute serve should simulate the Fastly platform to enable you to test a package on your local machine. Currently this configuration section supports defining backends, dictionaries, and object stores.

To see how this configuration is used, read more about testing and debugging Compute@Edge.

Data model

Property name	Type	Description
`local_server`	Table	Describes the configuration for the local server built into the Fastly CLI, which can be invoked with `fastly compute serve`.
`└─ backends`	Table	A list of backends that should be provided by the local server.
`└─ {name}`	Table	Each backend is a section whose name is the string used as the backend ID in the package code.
`└─ url`	String	The URL of the server to which to route requests made by the package to this backend. Must contain a scheme and host. May contain a port or path prefix. See below for examples.
`└─ override_host`	String	Used to override the Host header in requests sent to the local server's backends.
`└─ config_stores`	Table	A list of config stores that should be provided by the local server.
`└─ {name}`	Table	Each dictionary is a section whose name is the string used as the dictionary ID in the package code.
`└─ content`	Table	A section containing inline dictionary items. Only used when `format` is set to `inline-toml`. See below for examples.
`└─ {key}`	String	Individual dictionary items.
`└─ file`	String	The path to a JSON file containing the dictionary items that the local server should provide to the app. Only used when `format` is set to `file`. See below for examples.
`└─ format`	String	The format of the dictionary items. Supports `json`, `inline-toml`.
`└─ object_stores`	Table	A list of object stores that should be provided by the local server.
`└─ {name}`	Table	Each object store is a section whose name is the string used as the resource link ID, holding an array of objects.
`└─ key`	String	The name of the object in the store.
`└─ path`	String	Points to a file relative to the project root.
`└─ data`	String	Bytes of data. Note that `path` and `data` are exclusive parameters.
`└─ secret_stores`	Table	A list of secret stores that should be provided by the local server.
`└─ {name}`	Table	Each secret store is a section whose name is the string used as the resource link ID, holding an array of secrets.
`└─ key`	String	The name of the secret in the store.
`└─ path`	String	Points to a file relative to the project root.
`└─ data`	String	Bytes of data. Note that `path` and `data` are exclusive parameters.
`└─ geolocation`	Table	A set of geolocation data to use for geolocation related SDK features.
`└─ format`	String	The format of the geolocation data. Supports `json`, `inline-toml`.
`└─ file`	String	The path to a JSON file containing the geolocation data that the local server should provide to the app. Only used when `format` is set to `file`. See below for examples.
`└─ addresses`	Table	A table of IP addresses, where each address maps to a set of geolocation data.
`└─ {ipaddress}`	Table	An IP address
`└─ {geo_variable}`	String	A geolocation variable. Available keys are `as_name`, `as_number`, `area_code`, `city`, `conn_speed`, `conn_type`, `continent`, `country_code`, `country_code3`, `country_name`, `latitude`, `longitude`, `metro_code`, `postal_code`, `proxy_description`, `proxy_type`, `region` and `utc_offset`.

Backends

Test backends are local or remote servers to which we should route traffic coming from your package, and act as substitutes for real backends. Each backend is a table and contains a single url key:

fastly.toml

TOML

[local_server]
  [local_server.backends]
    [local_server.backends.backend_a]
      url = "http://127.0.0.1/"
    [local_server.backends.backend_b]
      url = "https://example.org/"
      override_host = "example.org"
    [local_server.backends.backend_c]
      url = "https://example.org/path/prefix"
      override_host = "example.org"
    [local_server.backends.backend_d]
      url = "http://127.0.0.1:8080/"

If the url property contains a path component, then any request to that backend will be prefixed with that path. For the example shown above, a request to GET /foo issued by your package to the backend_c backend will result in a request being made to https://example.org/path/prefix/foo.

HINT: Using a path prefix is useful if your service has multiple backends and, in your test environment, you have a single server that is standing in for all of the backends. The one backend-mocking server can use the path prefix to determine which backend is being targeted by the fetch.

Config stores

Test stores can be defined either as local JSON files that contain the items your app requires to run, or they can be written inline into the fastly.toml file.

For example, if you had an app that required a set of localized strings to be loaded from a config store named strings:

strings.json

json

{
  "en.welcome": "welcome",
  "de.welcome": "willkommen",
  "fr.welcome": "bienvenue",
  "es.welcome": "bienvenido"
}

You can then reference this store in your fastly.toml file:

fastly.toml

TOML

[local_server]
  [local_server.config_stores]
    [local_server.config_stores.strings]
      file = "strings.json"
      format = "json"

Alternatively you can inline that file directly within the fastly.toml:

fastly.toml

TOML

[local_server]
  [local_server.config_stores]
    [local_server.config_stores.strings]
      format = "inline-toml"
    [local_server.config_stores.strings.content]
      "en.welcome" = "welcome"
      "de.welcome" = "willkommen"
      "fr.welcome" = "bienvenue"
      "es.welcome" = "bienvenido"

Object and secret stores

Local object stores and secret stores can be made available to your application, using data either embedded in the TOML file or loaded from a referenced path. For example:

fastly.toml

TOML

[local_server]
object_stores.example_store = [{key = "first", data = "This is some data"},
                               {key = "second", path = "../test/data/some-object.txt"}]

Secret stores share the same syntax as object stores, but are defined within the secret_stores section of the config.

Geolocation

Compute@Edge SDKs expose geolocation-related features to provide information about the origin of a request. When running within the local server, geolocation data is mocked and if you wish can be defined in the configuration:

[local_server.geolocation]
  format = "inline-toml"
  [local_server.geolocation.addresses]
    [local_server.geolocation.addresses."127.0.0.1"]
      as_name = "Dummy, Inc."
      city = "New York"
      latitude = 1.23
      longitude = 1.23

Alternatively, you can reference an external file by setting format to "json" and including a file property containing a path to a JSON file. The format of the JSON file is an object where keys are IP addresses and values are the geolocation properties for that IP:

{
  "127.0.0.1": {
    "as_name": "Fastly Test",
    "as_number": 12345,
    "area_code": 123,
    "city": "Test City",
    "conn_speed": "broadband",
    "conn_type": "wired",
    "continent": "NA",
    "country_code": "CA",
    "country_code3": "CAN",
    "country_name": "Canada",
    "latitude": 12.345,
    "longitude": 54.321,
    "metro_code": 0,
    "postal_code": "12345",
    "proxy_description": "?",
    "proxy_type": "?",
    "region": "CA-BC",
    "utc_offset": -700
  }
}

Environments

The local server may be invoked with an --env argument that specifies the name of an environment. Environments are defined by creating files of the form fastly.{ENV-NAME}.toml (e.g., fastly.staging.toml), alongside the fastly.toml file. Environment-specific files define an alternative configuration for [local_testing].

For example, the following configuration matches the one above, except that it defines a different URL for backend_b:

fastly.staging.toml

TOML

[local_server]
  [local_server.backends]
    [local_server.backends.backend_a]
      url = "http://127.0.0.1/"
    [local_server.backends.backend_b]
      url = "http://localhost:1234/"
    [local_server.backends.backend_c]
      url = "https://example.org/path/prefix"
    [local_server.backends.backend_d]
      url = "http://127.0.0.1:8080/"

Setup information

The optional [setup] section of the fastly.toml file allows the Fastly CLI and web interface to provide a smarter experience when a deployment of a package requires a Fastly service to be created, normally when you run fastly compute deploy for the first time.

Compute@Edge programs are able to use features of Fastly services configured outside the program by referring to the feature - such as a backend or dictionary - by name. It's therefore important that when deploying a C@E program, the service it is deployed to has a set of configured features matching the expectations of the package code. For example, if the program reads values from a dictionary called "config", then there must be a "config" dictionary in the same service.

Starter kits may include [setup] in their fastly.toml file so that the Fastly CLI has all the information needed to create a service in which that starter kit can be deployed.

Once a Compute@Edge project is associated with a Fastly service, the [setup] data is no longer used, and the service configuration can be managed normally via the web interface, the API, using CLI commands, or third party orchestration tooling.

Data model

Property name	Type	Description
`setup`	Table	Describes a set of service configuration that works with the code in the package.
`└─ backends`	Table	A list of backends that are required to be created on a first run of `compute deploy`.
`└─ {name}`	Table	The name of the backend used to connect to it from inside the package code, e.g. "api". Required.
`└─ description`	String	Label to describe the backend, e.g. "API origin server".
`└─ address`	String	Hostname or IP address of the backend.
`└─ port`	Number	Port number of the backend.
`└─ config_stores`	Table	A list of config stores that are required to be created on a first run of `compute deploy`.
`└─ {name}`	Table	The name of the config store used to reference it from inside the package code, e.g. "config". Required.
`└─ description`	String	Label to describe the store, e.g. "Configuration settings".
`└─ items`	Table	List of predefined store items for stores requiring a fixed set of entries.
`└─ {key}`	Table	The key for the store item. Required.
`└─ value`	String	Suggested value for the store item.
`└─ input_type`	String	Input type hint, allowing for validation and improved input form usability (not supported in the Fastly CLI). One of `string`, `number`, `integer`, `email`, `url`, `http-header`, `password`.
`└─ description`	String	Label to describe the key/value pair.
`└─ log_endpoints`	Table	A list of log endpoints that are required to be created on a first run of `compute deploy`.
`└─ {name}`	Table	The name of the log endpoint used to reference it from inside the package code, e.g. "bigquery_requests". Required.
`└─ provider`	String	The name of the log provider (e.g. BigQuery, NewRelic etc). Used as part of a generic message to the user indicating the type of provider needed.

Example setup configuration

The following configuration demonstrates how to configure two separate backends (named httpbin and httpme) and a dictionary populated with two keys (named s3-primary-host and s3-fallback-host):

[setup]

  [setup.backends]

    [setup.backends.httpbin]
      address = "httpbin.org"
      description = "A simple HTTP Request & Response Service."
      port = 443

    [setup.backends.httpme]
      address = "http-me.glitch.me"
      description = "HTTP me is a tiny express app initally designed to replicate the features of HTTPBin.org"
      port = 443

  [setup.dictionaries]

    [setup.dictionaries.service_config]
      description = "Configuration data for my service"

      [setup.dictionaries.service_config.items]

        [setup.dictionaries.service_config.items.s3-primary-host]
          value = "eu-west-2"

        [setup.dictionaries.service_config.items.s3-fallback-host]
          value = "us-west-1"

Declaring resources without values

It's possible to define resources that are required, but to not provide any configuration for them, other than a name.

fastly.toml [setup] sections with no fields defined

TOML

[setup.backends.api]
[setup.backends.content]
[setup.log_endpoints.request_logger]

This configuration states that two backend resources (one called 'api' and the other 'content') and a log endpoint resource (called 'request_logger') are required. When presented with this configuration, the Fastly CLI will prompt the user for the fields relevant to each resource, and a default value provided within the prompt if applicable.

On this page:

Example
Reference
Scripts
Local server
Setup information