github.com/avenga/couper@v1.12.2/DOCKER.md (about) 1 # Couper 2 3  4 5 Couper is designed to support developers building and operating API-driven Web projects by offering security and observability functionality in a frontend gateway component. 6 7 _For additional information, tutorials and documentation, please visit the [Couper repository](https://github.com/avenga/couper)._ 8 9 ## Usage 10 11 Couper requires a [configuration file](https://docs.couper.io/configuration/configuration-file) which has to be provided on start. 12 See our [documentation](https://docs.couper.io/getting-started/introduction) on how to configure _Couper_. 13 14 This image contains a basic configuration to serve files from `/htdocs` directory. 15 16 ```sh 17 $ docker run --rm -p 8080:8080 -v `pwd`:/htdocs avenga/couper 18 ``` 19 20 ## Command 21 22 The entrypoint of the image is the `/couper` binary. The command is `run`. 23 24 Therefore `docker run avenga/couper` runs `/couper run -d /conf`. 25 26 The [directory argument](https://docs.couper.io/configuration/command-line#basic-options) allows you to mount multiple configuration files to the `/conf` directory. 27 28 You could also use other commands directly: 29 30 ```sh 31 $ docker run avenga/couper version 32 33 $ docker run avenga/couper run -watch -p 8081 34 ``` 35 36 ## Environment Variables 37 38 ### Basic Environment Variables 39 40 | Variable | Default | Description | 41 |:-------------------------|:-------------|:----------------------------------------------------------------------------------------------------------------| 42 | COUPER_FILE | `couper.hcl` | Path to the configuration file. | 43 | COUPER_FILE_DIRECTORY | `""` | Path to the configuration files directory. | 44 | COUPER_DEFAULT_PORT | `8080` | Sets the default port to the given value and does not override explicit `[host:port]` configurations from file. | 45 | COUPER_ENVIRONMENT | `""` | Name of environment in which Couper is currently running. | 46 | COUPER_WATCH | `false` | Set to `true` to watch for configuration file changes. | 47 | COUPER_WATCH_RETRIES | `5` | Maximal retry count for configuration reloads which could not bind the configured port. | 48 | COUPER_WATCH_RETRY_DELAY | `500ms` | Delay duration before next attempt if an error occurs. | 49 50 ### Oberservation Environment Variables 51 52 | Variable | Default | Description | 53 |:-------------------------------------|:----------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 54 | COUPER_HEALTH_PATH | `/healthz` | Path for health-check requests for all servers and ports. | 55 | COUPER_LOG_FORMAT | `common` | Can be set to `json` output which is the _container default_. | 56 | COUPER_LOG_LEVEL | `info` | Set the log-level to one of: `info`, `panic`, `fatal`, `error`, `warn`, `debug`, `trace`. | 57 | COUPER_LOG_PARENT_FIELD | `""` | An option for `json` log format to add all log fields as child properties. | 58 | COUPER_LOG_PRETTY | `false` | Global option for `json` log format which pretty prints with basic key coloring. | 59 | COUPER_LOG_TYPE_VALUE | `couper_daemon` | Value for the runtime log field `type`. | 60 | COUPER_ACCESS_LOG_REQUEST_HEADERS | `User-Agent, Accept, Referer` | A comma separated list of request header names whose values should be logged. | 61 | COUPER_ACCESS_LOG_RESPONSE_HEADERS | `Cache-Control, Content-Encoding, Content-Type, Location` | A comma separated list of response header names whose values should be logged. | 62 | COUPER_ACCESS_LOG_TYPE_VALUE | `couper_access` | Value for the log field `type`. | 63 | COUPER_BACKEND_LOG_REQUEST_HEADERS | `User-Agent, Accept, Referer` | A comma separated list of request header names whose values should be logged. | 64 | COUPER_BACKEND_LOG_RESPONSE_HEADERS | `Cache-Control, Content-Encoding, Content-Type, Location` | A comma separated list of response header names whose values should be logged. | 65 | COUPER_BACKEND_LOG_TYPE_VALUE | `couper_backend` | Value for the log field `type`. | 66 | COUPER_REQUEST_ID_ACCEPT_FROM_HEADER | `""` | Name of a client request HTTP header field that transports the `request.id` which Couper takes for logging and transport to the backend (if configured). | 67 | COUPER_REQUEST_ID_BACKEND_HEADER | `Couper-Request-ID` | Name of a HTTP header field which Couper uses to transport the `request.id` to the backend. | 68 | COUPER_REQUEST_ID_CLIENT_HEADER | `Couper-Request-ID` | Name of a HTTP header field which Couper uses to transport the `request.id` to the client. | 69 | COUPER_REQUEST_ID_FORMAT | `common` | If set to `uuid4` a rfc4122 uuid is used for `request.id` and related log fields. | 70 | COUPER_SERVER_TIMING_HEADER | `false` | If enabled, Couper includes an additional [Server-Timing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing) HTTP response header field detailing connection and transport relevant metrics for each backend request. | 71 | COUPER_BETA_METRICS | `false` | Option to enable the prometheus [metrics](https://docs.couper.io/observation/metrics) exporter. | 72 | COUPER_BETA_METRICS_PORT | `9090` | Prometheus exporter listen port. | 73 | COUPER_BETA_SERVICE_NAME | `couper` | The service name which applies to the `service_name` metric labels. | 74 75 ### TLS Environment Variables 76 77 | Variable | Default | Description | 78 |:-----------------------|:--------|:------------------------------------------------------------------------------------------------------------------------------------------------------------| 79 | COUPER_CA_FILE | `""` | Option for adding the given PEM encoded ca-certificate to the existing system certificate pool for all outgoing connections. | 80 | COUPER_HTTPS_DEV_PROXY | `""` | List of TLS port mappings to define the TLS listen port and the target one. A self-signed certificate will be generated on the fly based on given hostname. | 81 | COUPER_SECURE_COOKIES | `""` | If set to `"strip"`, the `Secure` flag is removed from all `Set-Cookie` HTTP header fields. | 82 83 ### Profiling Environment Variables 84 85 | Variable | Default | Description | 86 |:------------------|:--------|:------------------------------| 87 | COUPER_PPROF | `false` | Enables profiling. | 88 | COUPER_PPROF_PORT | `6060` | Port for profiling interface. | 89 90 ### Timing Environment Variables 91 92 | Variable | Default | Description | 93 |:----------------------------------|:--------|:------------------------------------------------------------------------------------------------------------| 94 | COUPER_TIMING_IDLE_TIMEOUT | `60s` | The maximum amount of time to wait for the next request on client connections when keep-alives are enabled. | 95 | COUPER_TIMING_READ_HEADER_TIMEOUT | `10s` | The amount of time allowed to read client request headers. | 96 | COUPER_TIMING_SHUTDOWN_DELAY | `0` | The amount of time the server is marked as unhealthy until calling server close finally. | 97 | COUPER_TIMING_SHUTDOWN_TIMEOUT | `0 ` | The maximum amount of time allowed to close the server with all running connections. | 98 99 ### Surrounding Architecture Environment Variables 100 101 | Variable | Default | Description | 102 |:----------------------------|:--------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 103 | COUPER_ACCEPT_FORWARDED_URL | `""` | Which `X-Forwarded-*` request headers should be accepted to change the [request variables](https://docs.couper.io/configuration/variables#request) `url`, `origin`, `protocol`, `host`, `port`. Comma-separated list of values. Valid values: `proto`, `host`, `port`. | 104 | COUPER_NO_PROXY_FROM_ENV | `false` | Disables the connect hop to configured [proxy via environment](https://godoc.org/golang.org/x/net/http/httpproxy). | 105 | COUPER_XFH | `false` | Global configurations which uses the `X-Forwarded-Host` header instead of the request host. |