{"id":13563928,"url":"https://github.com/mendhak/docker-http-https-echo","last_synced_at":"2025-04-14T01:58:48.519Z","repository":{"id":39850270,"uuid":"114048398","full_name":"mendhak/docker-http-https-echo","owner":"mendhak","description":"Docker image that echoes request data as JSON; listens on HTTP/S, useful for debugging.","archived":false,"fork":false,"pushed_at":"2025-03-22T20:16:46.000Z","size":855,"stargazers_count":697,"open_issues_count":6,"forks_count":145,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-14T01:58:44.236Z","etag":null,"topics":["docker","echo-server","https","web-debug"],"latest_commit_sha":null,"homepage":"https://code.mendhak.com/docker-http-https-echo/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mendhak.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-12T23:03:51.000Z","updated_at":"2025-04-11T09:12:59.000Z","dependencies_parsed_at":"2023-02-01T04:05:29.162Z","dependency_job_id":"5676edea-b7ac-4bee-8077-63d8b8bd8c5d","html_url":"https://github.com/mendhak/docker-http-https-echo","commit_stats":{"total_commits":260,"total_committers":20,"mean_commits":13.0,"dds":"0.19615384615384612","last_synced_commit":"dc58452925ac60a1ae50d45954e6c44b8a950e67"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendhak%2Fdocker-http-https-echo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendhak%2Fdocker-http-https-echo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendhak%2Fdocker-http-https-echo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendhak%2Fdocker-http-https-echo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mendhak","download_url":"https://codeload.github.com/mendhak/docker-http-https-echo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809032,"owners_count":21164895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","echo-server","https","web-debug"],"created_at":"2024-08-01T13:01:24.655Z","updated_at":"2025-04-14T01:58:48.497Z","avatar_url":"https://github.com/mendhak.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"[![pulls](https://img.shields.io/docker/pulls/mendhak/http-https-echo.svg?style=for-the-badge\u0026logo=docker)](https://hub.docker.com/r/mendhak/http-https-echo)\n[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/mendhak/http-https-echo?color=lightblue\u0026label=latest\u0026sort=semver\u0026style=for-the-badge)](https://hub.docker.com/r/mendhak/http-https-echo)\n[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mendhak/docker-http-https-echo/build.yml?color=darkgreen\u0026style=for-the-badge\u0026branch=master)](https://github.com/mendhak/docker-http-https-echo/actions?query=workflow%3ABuild)\n\n\n`mendhak/http-https-echo` is a Docker image that can echo various HTTP request properties back to client in the response, as well as in the Docker container logs.\nIt comes with various options that can manipulate the response output, see the table of contents for a full list.\n\n![browser](./screenshots/screenshot.png)\n\nThe image is available on [Docker Hub](https://hub.docker.com/r/mendhak/http-https-echo): `mendhak/http-https-echo:36`\nThe image is available on [Github Container Registry](https://github.com/mendhak/docker-http-https-echo/pkgs/container/http-https-echo): `ghcr.io/mendhak/http-https-echo:36`\n\nPlease do not use the `:latest` tag as it will break without warning, use a specific version instead.\n\nThis image is executed as non root by default and is fully compliant with Kubernetes or Openshift deployment.\n\n\n- [Basic Usage](#basic-usage)\n- [Choose your ports](#choose-your-ports)\n- [Use your own certificates](#use-your-own-certificates)\n- [Decode JWT header](#decode-jwt-header)\n- [Disable ExpressJS log lines](#disable-expressjs-log-lines)\n- [Do not log specific path](#do-not-log-specific-path)\n- [JSON payloads and JSON output](#json-payloads-and-json-output)\n- [No newlines](#no-newlines)\n- [Send an empty response](#send-an-empty-response)\n- [Custom status code](#custom-status-code)\n- [Set response Content-Type](#set-response-content-type)\n- [Add a delay before response](#add-a-delay-before-response)\n- [Only return body in the response](#only-return-body-in-the-response)\n- [Include environment variables in the response](#include-environment-variables-in-the-response)\n- [Configuring CORS policy](#setting-corscross-origin-resource-sharing-headers-in-the-response) \n- [Client certificate details (mTLS) in the response](#client-certificate-details-mtls-in-the-response)\n- [Preserve the case of headers in response body](#preserve-the-case-of-headers-in-response-body)\n- [Override the response body with a file](#override-the-response-body-with-a-file)\n- [Prometheus Metrics](#prometheus-metrics)\n- [Screenshots](#screenshots)\n- [Building](#building)\n- [Changelog](#changelog)\n\n\n## Basic Usage\n\nRun with Docker\n\n    docker run -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:36\n\nOr run with Docker Compose\n\n    docker-compose up\n\nThen, issue a request via your browser or curl, and watch the response, as well as container log output.\n\n    curl -k -X PUT -H \"Arbitrary:Header\" -d aaa=bbb https://localhost:8443/hello-world\n\n\n## Choose your ports\n\nYou can choose a different internal port instead of 8080 and 8443 with the `HTTP_PORT` and `HTTPS_PORT` environment variables.\n\nIn this example I'm setting http to listen on 8888, and https to listen on 9999.\n\n     docker run -e HTTP_PORT=8888 -e HTTPS_PORT=9999 -p 8080:8888 -p 8443:9999 --rm -t mendhak/http-https-echo:36\n\n\nWith docker compose, this would be:\n\n    my-http-listener:\n        image: mendhak/http-https-echo:36\n        environment:\n            - HTTP_PORT=8888\n            - HTTPS_PORT=9999\n        ports:\n            - \"8080:8888\"\n            - \"8443:9999\"\n\n\n## Use your own certificates\n\nThe certificates are at `/app/fullchain.pem` and `/app/privkey.pem`.\n\nYou can use volume mounting to substitute the certificate and private key with your own.\n\n    my-http-listener:\n        image: mendhak/http-https-echo:36\n        ports:\n            - \"8080:8080\"\n            - \"8443:8443\"\n        volumes:\n            - /etc/ssl/certs/ssl-cert-snakeoil.pem:/app/fullchain.pem\n            - /etc/ssl/private/ssl-cert-snakeoil.key:/app/privkey.pem\n\nYou can use the environment variables `HTTPS_CERT_FILE` and `HTTPS_KEY_FILE` to define the location of existing certificate and private key inside container.\n\n\n## Decode JWT header\n\nIf you specify the header that contains the JWT, the echo output will contain the decoded JWT.  Use the `JWT_HEADER` environment variable for this.\n\n    docker run -e JWT_HEADER=Authentication -p 8080:8080 -p 8443:8443 --rm -it mendhak/http-https-echo:36\n\n\nNow make your request with `Authentication: eyJ...` header (it should also work with the `Authentication: Bearer eyJ...` schema too):\n\n     curl -k -H \"Authentication: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c\" http://localhost:8080/\n\nAnd in the output you should see a `jwt` section.\n\n## Disable ExpressJS log lines\n\nIn the log output set the environment variable `DISABLE_REQUEST_LOGS` to true, to disable the specific ExpressJS request log lines. The ones like `::ffff:172.17.0.1 - - [03/Jan/2022:21:31:51 +0000] \"GET /xyz HTTP/1.1\" 200 423 \"-\" \"curl/7.68.0\"`.  The JSON output will still appear.\n\n    docker run --rm -e DISABLE_REQUEST_LOGS=true --name http-echo-tests -p 8080:8080 -p 8443:8443 -t mendhak/http-https-echo:36\n\n\n## Do not log specific path\n\nSet the environment variable `LOG_IGNORE_PATH` to a path you would like to exclude from verbose logging to stdout.\nThis can help reduce noise from healthchecks in orchestration/infrastructure like Swarm, Kubernetes, ALBs, etc.\n\n     docker run -e LOG_IGNORE_PATH=/ping -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:36\n\n\nWith docker compose, this would be:\n\n    my-http-listener:\n        image: mendhak/http-https-echo:36\n        environment:\n            - LOG_IGNORE_PATH=/ping\n        ports:\n            - \"8080:8080\"\n            - \"8443:8443\"\n\n\n## JSON payloads and JSON output\n\nIf you submit a JSON payload in the body of the request, with Content-Type: application/json, then the response will contain the escaped JSON as well.\n\nFor example,\n\n    curl -X POST -H \"Content-Type: application/json\" -d '{\"a\":\"b\"}' http://localhost:8080/\n\nWill contain a `json` property in the response/output.\n\n        ...\n        \"xhr\": false,\n        \"connection\": {},\n        \"json\": {\n            \"a\": \"b\"\n        }\n    }\n\n## No newlines\n\nYou can disable new lines in the log output by setting the environment variable `LOG_WITHOUT_NEWLINE`. For example,\n\n```bash\ndocker run -e LOG_WITHOUT_NEWLINE=true -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:36\n```\n\n## Send an empty response\n\nYou can disable the JSON output in the response by setting the environment variable `ECHO_BACK_TO_CLIENT`. For example,\n\n```bash\ndocker run -e ECHO_BACK_TO_CLIENT=false -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:36\n```\n\n## Custom status code\n\nUse `x-set-response-status-code` to set a custom status code.\n\nYou can send it as a header:\n\n```bash\ncurl -v -H \"x-set-response-status-code: 401\" http://localhost:8080/\n```\n\nYou can send it as a querystring parameter:\n\n```bash\ncurl -v http://localhost:8080/some/path?x-set-response-status-code=401\n```\n\nThat will cause the reponse status code to be:\n\n```\n HTTP/1.1 401 Unauthorized\n```\n\n## Set response Content-Type\n\nUse `x-set-response-content-type` to set the Content-Type of the response.\n\nYou can send it as a header:\n\n```bash\ncurl -H \"X-Set-Response-Content-Type: text/plain\" -kv https://localhost:8443/\n```\n\nYou can send it as a querystring parameter:\n\n```bash\ncurl  -kv https://localhost:8443/path?x-set-response-content-type=text/plain\n```\n\nThis will cause the response content type to be:\n\n```\n\u003c Content-Type: text/plain; charset=utf-8\n```\n\n\n## Add a delay before response\n\nUse `x-set-response-delay-ms` to set a custom delay in milliseconds.  This will allow you to simulate slow responses.\n\nYou can send it as a header:\n\n```bash\ncurl -v -H \"x-set-response-delay-ms: 6000\" http://localhost:8080/\n```\n\nYou can send it as a querystring parameter:\n\n```bash\ncurl -v http://localhost:8080/some/path?x-set-response-delay-ms=6000\n```\n\n## Only return body in the response\n\nUse the querystring parameter, `response_body_only=true` to get just the request body in the response, none of the associated metadata.\n\n```bash\ncurl -s -k -X POST -d 'cauliflower' http://localhost:8080/a/b/c?response_body_only=true\n```\n\nThe output will be 'cauliflower'.\n\n## Include environment variables in the response\n\nYou can have environment variables (that are visible to the echo server's process) added to the response body.  Because this could contain sensitive information, it is not a default behavior.\n\nPass the `ECHO_INCLUDE_ENV_VARS=1` environment variable in.\n\n```bash\ndocker run -d --rm -e ECHO_INCLUDE_ENV_VARS=1 --name http-echo-tests -p 8080:8080 -p 8443:8443 -t mendhak/http-https-echo:36\n```\n\nThen do a normal request via curl or browser, and you will see the `env` property in the response body.\n\n## Setting CORS(Cross-Origin Resource Sharing) headers in the response\n\nEnable CORS headers in response by setting the environment variable `CORS_ALLOW_ORIGIN` to the list of allowed origins.\nCORS configuration can be further fine-tuned by using the following environment variables:\n\n- **`CORS_ALLOW_METHODS`**: List of Http methods allowed.\n- **`CORS_ALLOW_HEADERS`**: List of headers allowed.\n- **`CORS_ALLOW_CREDENTIALS`**: Comma-separated list of origin URLs from which the policy allows credentials to be sent.\n\nNone of these CORS settings can be set without setting the `CORS_ALLOW_ORIGIN` first. By default, they will all be missing when only the `CORS_ALLOW_ORIGIN` is set and need to be explicitly specified alongside `CORS_ALLOW_ORIGIN`.\n\n\n## Client certificate details (mTLS) in the response\n\nTo get client certificate details in the response body, start the container with `MTLS_ENABLE=1` environment variable.  When passing a client certificate, the details about that certificate can be echoed back in the response body. The client certificate will not be validated.\n\nFor example, invoke using curl, passing a certificate and key.\n\n```bash\ncurl -k --cert cert.pem --key privkey.pem  https://localhost:8443/\n```\n\nThe response body will contain details about the client certificate passed in.\n\nIf you browse to https://localhost:8443/ in Firefox, you won't get prompted to supply a client certificate unless you have [an imported certificate by the same issuer as the server](https://superuser.com/questions/1043415/firefox-doesnt-ask-me-for-a-certificate-when-visiting-a-site-that-needs-one). If you need browser prompting to work, you'll need to follow the 'use your own certificates' section.  Firefox needs the imported certificate to be in a PKCS12 format, so if you have a certificate and key already, you can combine them using\n\n```bash\nopenssl pkcs12 -export -in cert.pem -inkey privkey.pem -out certpkcs12.pfx\n```\n\n## Preserve the case of headers in response body\n\nBy default, the headers in the response body are lowercased. To attempt to preserve the case of headers in the response body, set the environment variable `PRESERVE_HEADER_CASE` to true.\n\n```bash\ndocker run -e PRESERVE_HEADER_CASE=true -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:36\n```\n\n## Override the response body with a file\n\nTo override the response body with a file, set the environment variable `OVERRIDE_RESPONSE_BODY_FILE_PATH` to a file path.  \nThe file path needs to be in the `/app` directory.  \n\n```bash\ndocker run -d --rm -v ${PWD}/test.html:/app/test.html -p 8080:8080 -e OVERRIDE_RESPONSE_BODY_FILE_PATH=/test.html -t mendhak/http-https-echo:36\n```\n\n\n## Prometheus Metrics\n\nTo expose http performance metrics, set the `PROMETHEUS_ENABLED` environment variable to true, the metrics will be available at `/metrics`. This uses the [`express-prom-bundle`](https://github.com/jochen-schweizer/express-prom-bundle) middleware\n\nYou can configure these metrics using the following variables:\n\n| Variable                | Description                                   | Default Value |\n| ----------------------- | --------------------------------------------- | ------------- |\n| PROMETHEUS_ENABLED      | Toggles on the prometheus middleware          | false         |\n| PROMETHEUS_METRICS_PATH | The path at which the metrics will be visible | /metrics      |\n| PROMETHEUS_WITH_PATH    | Partitions the metrics by the requested path  | false         |\n| PROMETHEUS_WITH_METHOD  | Partitions the metrics by HTTP method         | true          |\n| PROMETHEUS_WITH_STATUS  | Partitions the metrics by HTTP status         | true          |\n| PROMETHEUS_METRIC_TYPE  | Sets the type of metric, histogram or summary | summary       |\n\n\u003e Please check the middleware [documentation](https://github.com/jochen-schweizer/express-prom-bundle#options) for more details.\n\n## Screenshots\n\n#### Curl output\n\n![curl](./screenshots/screenshot2.png)\n\n#### `docker logs` output\n\n![dockerlogs](./screenshots/screenshot3.png)\n\n\n\n## Building\n\n    docker build -t mendhak/http-https-echo .\n\nRun some tests to make sure features are working as expected.\n\n    ./tests.sh\n\nTo create a new image on Docker Hub, I need to create a tag and push it.\n\n    git tag -s 16\n    git push --tags\n\n\n## Changelog\n\nSee the [changelog](CHANGELOG.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmendhak%2Fdocker-http-https-echo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmendhak%2Fdocker-http-https-echo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmendhak%2Fdocker-http-https-echo/lists"}