1. Home
2. Reference documentation
3. Compute@Edge

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:

1. attribution of the package (e.g., name, author)
2. information required by the fastly CLI to compile and upload it to a compatible Fastly service
3. configuration of local server environments
4. 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:

1manifest_version = 3
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):

Scripts

The [scripts] section instructs the Fastly CLI to run certain commands as part of its compile process.

The build property tells the CLI how to compile your project. It must produce a bin/main.wasm binary. From version v4.0.0 onward, configuring the build property is required. When you fastly compute init the template project we set up for you will have a build script suitable for the language you've chosen to use.

Customizing the build script can be useful when you want to use an alternative build process. For example although our JavaScript SDK doesn't require a module bundler such as Webpack, you could choose to use one by adding it to the build command:

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

This will prompt Webpack to bundle 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. build can also be used to swap out an alternative compiler, e.g., to take advantage of TinyGo's smaller memory footprint in Go projects.

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 for further optimization of the produced Wasm binary if required. Here is an example which defines a post_build step for a project built using our Go SDK:

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

env_vars should contain an array of key/value pairs defining environment variables you want to have set within the context of the shell that executes your build script.

Here is an example of defining env_vars for a Go project that wants to use the standard Go compiler instead of the default TinyGo:

[scripts]
env_vars = ["GOARCH=wasm", "GOOS=wasip1"]
build = "go build -o bin/main.wasm ."

post_init runs after a project has been initialized, and is ideally suited to run dependency installation processes, such as npm install in the case of JavaScript projects.

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.

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

Data model

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:

[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.

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:

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

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

[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:

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

KV and secret stores

Local KV 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:

[local_server]
  [local_server.kv_stores]
    [[local_server.kv_stores.example_store]]
      key = "first"
      data = "This is some data"
    [[local_server.kv_stores.example_store]]
      key = "second"
      file = "../test/data/some-object.txt"

[local_server]
  [local_server.secret_stores]
    [[local_server.secret_stores.example_store]]
      key = "api-key"
      data = "api-key-value"
    [[local_server.secret_stores.example_store]]
      key = "cert"
      file = "../test/data/some-cert"

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:

[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 config store - 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 config store called "config", then there must be a "config" config store 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

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.config_stores]

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

      [setup.config_stores.service_config.items]

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

        [setup.config_stores.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.

[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.