Overview

Couper is a lightweight open-source API gateway that acts as an entry point for clients to your application and an exit point to upstream services.

It adds access control, observability, and back-end connectivity on a separate layer. This will keep your core application code simpler.

Couper does not need any special development skills and offers easy configuration and integration.

Visit docs.couper.io

Getting Started

Couper is available as container image or as binary from the latest release on GitHub.

To download/install Couper with homebrew, open your terminal and execute:

$ brew tap coupergateway/couper && brew install couper

Couper needs a configuration file to know what to do. Create an empty couper.hcl file.

Copy/paste the following configuration to the file and save it:

server {
	endpoint "/**" {
        response {
            body = "Hello World!"
        }
    }
}

Then start Couper:

$ couper run -f couper.hcl

{"level":"info","message":"couper is serving: 0.0.0.0:8080","timestamp":"2022-01-03T04:20:00+01:00","type":"couper_daemon"}

Now Couper is serving on your computer's port 8080. Point your browser or curl to http://localhost:8080/ to see what's going on.

Press CTRL+c to stop the process. Visit the Couper repository for reference or go on with the examples.

Beautiful Configuration

The syntax of the configuration file is based on HCL 2.0, a configuration language by HashiCorp.

The result is easy to read, yet powerful and expressive.

Get VS Code Extension

Full Example Repository

Our example repository consists of small, ready-to-use examples that guide you through the configuration step by step. Configure your file and SPA serving, create virtual endpoints, group them in APIs, and protect them with JSON Web Tokens.

Full Example Repository

Configuration Examples

The following examples are intended to give you a glance of Couper's core concepts and functionality. See for yourself what a few lines of configuration can do for you.

server {

  files {
    document_root = "htdocs"
  }

  spa {
    bootstrap_file = "htdocs/index.html"
    paths = ["/**"]
  }
}

SPA Web serving

Every web application begins with a client loading an HTML page. That's why Couper contains a web server for simple file serving. Couper also takes care of the more complex web serving of SPA assets.

The files block configures Couper's file server. It needs to know which directory to serve (document_root). That's all it takes!

The spa block is responsible for serving the bootstrap document for all paths that match the paths list.

server {

  files {
    document_root = "htdocs"
  }

  spa {
    bootstrap_file = "htdocs/index.html"
    paths = ["/**"]
  }
}

Browse Full Example

Proxy API requests

Most modern web applications use APIs to get information for display, trigger actions, or check if a user is authorized to see or do certain things. These APIs may be part of your application or a third-party service running elsewhere.

This basic configuration defines an upstream backend service (https://httpbin.org) and "mounts" it on the local API endpoint /public/**.

server {

  endpoint "/public/**" {
    path = "/**"

    proxy {
      backend {
        origin = "https://httpbin.org"
      }
    }
  }
}

Browse Full Example

server {

  endpoint "/public/**" {
    path = "/**"

    proxy {
      backend {
        origin = "https://httpbin.org"
      }
    }
  }
}

server {

  endpoint "/private/**" {
    access_control = ["accessToken"]
    path = "/**"

    proxy {
      backend {
        origin = "https://httpbin.org"
      }
    }
  }
}

definitions {
  jwt "accessToken" {
    signature_algorithm = "RS256"
    key_file = "keys/public.pem"
    header = "Authorization"
  }
}

JWT access control

Most certainly, you don't want anyone to use your application without permission.

Couper offers JWT access control: configure your access control in the definitions block and secure your private endpoint by referencing the label.

server {

  endpoint "/private/**" {
    access_control = ["accessToken"]
    path = "/**"

    proxy {
      backend {
        origin = "https://httpbin.org"
      }
    }
  }
}

definitions {
  jwt "accessToken" {
    signature_algorithm = "RS256"
    key_file = "keys/public.pem"
    header = "Authorization"
  }
}

Browse Full Example

Reasons for Couper

Intuitive Configuration
Open Source

Language Independent
Don't Reinvent the Wheel

IDE Extension Available
Easy Integration

Cloud Native
Painless Re-Architecting

Changelog

Loading changelog...

Simple Integration

Couper releases are also provided as containers on DockerHub.

They are ready to use for your Continuous Integration builds and Kubernetes deployment. All settings can be configured via environment variables.

Due to its small resource footprint, you have many integration options regarding the required scaling or architecture setup.

Example: Kubernetes configuration

Get Docker Image