Getting Started

Couper is available as docker image from Docker Hub.
Running Couper requires a working Docker setup on your computer. Please visit the get started guide to get prepared.

To download/install Couper, open a terminal and execute:

$ docker pull avenga/couper
Couper needs a configuration file to know what to do. Create a directory with an empty couper.hcl file.

Copy/paste the following configuration to the file and save it:
server "hello" {
	endpoint "/**" {
        response {
            body = "Hello World!"   
        }
    }
}

Then start Couper in a docker container:
$ docker run --rm -p 8080:8080 -v "$(pwd)":/conf avenga/couper

{"addr":"0.0.0.0:8080","level":"info","message":"couper gateway is serving","timestamp":"2020-08-27T16:39:18Z","type":"couper"}
Now Couper is serving on your computer's port 8080 . Point your browser or curl to localhost:8080 to see what's going on.
Press CTRL+c to stop the container. Visit the Couper repository for reference or go on with the examples.

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 more simple.

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

Overview for Docs MobileFrontend API+ SPA Web Serving+ CORS+ JWT Validation & Signing+ SAML2 SSO+ OpenAPI 3 Schema Validation+ Logging+ Endpoint RoutingNo ControlFrontendUpstream API+ HTTP Proxy+ Request Manipulations+ Backend Configuration+ Timeouts, Connection Pools+ Authorization, OAuth2+ OpenAPI 3 Schema Validation+ LoggingBackend ServiceRemoteServiceProtectedSystem
Overview for DocsNo ControlFrontendBackendServiceFrontend APIUpstream API+ HTTP Proxy+ Request Manipulations+ Backend Configuration+ Timeouts, Connection Pools+ Authorization, OAuth2+ OpenAPI 3 Schema Validation+ Logging+ SPA Web Serving+ CORS+ JWT Validation & Signing+ SAML2 SSO+ OpenAPI 3 Schema Validation+ Logging+ Endpoint RoutingRemote ServiceProtected System

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 "example" {

  files {
    document_root = "htdocs"
  }

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

SPA Web serving

Every Web application begins with a client loading a 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 "example" {

  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 "example" {

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

    proxy {
      backend {
        origin = "https://httpbin.org"
      }
    }
  }
}
Browse Full Example
server "example" {

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

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

  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 "example" {

  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

  • Included
    Intuitive Configuration
  • Included
    Open Source
  • Included
    Language Independent
  • Included
    Don't Reinvent the Wheel
  • Included
    IDE Extension Available
  • Included
    Easy Integration
  • Included
    Cloud Native
  • Included
    Painless Re-Architecting

Changelog

Loading... Please wait.

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 foot-print you have many integration options regarding the required scaling or architecture setup.

Get Docker Image