Configuration File

The language for Couper's configuration file is HCL 2.0, a configuration language by HashiCorp.

IDE Extension

Couper provides its own IDE extension that adds Couper-specific highlighting and autocompletion to Couper's configuration file couper.hcl in Visual Studio Code.

Get it from the Visual Studio Market Place or visit the Extension repository.

File Name

The file-ending of your configuration file should be .hcl to have syntax highlighting within your IDE.

The file name defaults to couper.hcl in your working directory. This can be changed with the -f command-line flag. With -f /opt/couper/my_conf.hcl couper changes the working directory to /opt/couper and loads my_conf.hcl.

Basic File Structure

Couper's configuration file consists of nested configuration blocks that configure the gateway. There are a large number of options, but let's focus on the main structure first:

server "my_project" {
  files {
    # ...
  }

  spa {
    # ...
  }

  api {
    access_control = ["foo"]
    endpoint "/bar" {
      proxy {
        backend { }
      }
      request "sub-request" {
        backend { }
      }
      response { }
    }
  }
}

definitions {
  # ...
}

settings {
  # ...
}

defaults {
  # ...
}

• server main configuration block(s).
• files configuration block for file serving.
• spa configuration block for Web serving (SPA assets).
• api configuration block(s) that bundle(s) endpoints under a certain base path or access_control list.
• access_control attribute that sets access control for a block context.
• endpoint configuration block for Couper's entry points.
• proxy configuration block for a proxy request and response to an origin.
• backend configuration block for connection to local/remote backend service(s).
• request configuration block for a manual request to an origin.
• backend configuration block for connection to local/remote backend service(s).
• response configuration block for a manual client response.
• definitions block for predefined configurations, that can be referenced.
• settings block for server configuration which applies to the running instance.
• defaults block for default/fallback values.