mendhak/http-https-echo: An HTTP Request Echo Server

The mendhak/http-https-echo Docker container provides a simple, self-contained HTTP and HTTPS server that echoes back all information about an incoming request. This is an incredibly useful tool for debugging, testing, and understanding how applications (like web scanners, API clients, or browsers) send requests.

Key Use Cases

• Debugging HTTP Headers: Verify if custom headers, authentication tokens, or other specific headers are being sent correctly by your client application.
• Inspecting Request Bodies: For POST or PUT requests, you can see the exact content of the request body as received by the server.
• Understanding URL Paths and Query Parameters: Confirm that your client is constructing URLs with the correct paths and query strings.
• Testing Proxy Configurations: Ensure that proxies are forwarding requests as expected.
• Firewall and Network Testing: Check if network rules are allowing traffic to reach an intended destination.

Running the Container

The container exposes HTTP on port 8080 and HTTPS on port 8443. You can map these to any ports on your host machine. The --rm flag is used to automatically remove the container when it is stopped.

Basic HTTP Echo Server

To run an HTTP echo server on your host’s port 80:

docker run -it --rm -p 80:8080 mendhak/http-https-echo

You can then send a request to http://localhost/. The terminal running the container will show the detailed request information.

curl http://localhost/some/path?param=value -H "X-Custom-Header: test"

Basic HTTPS Echo Server

To run an HTTPS echo server on your host’s port 443:

docker run -it --rm -p 443:8443 mendhak/http-https-echo

When sending a request, you may need to use a flag like curl -k to ignore certificate warnings, as the container uses a self-signed certificate.

curl -k https://localhost/secure/path -H "Authorization: Bearer abc123"

Combined HTTP and HTTPS

You can run both simultaneously by mapping both ports:

docker run -it --rm -p 80:8080 -p 443:8443 mendhak/http-https-echo

Using Docker Compose

For a more declarative setup, you can use docker-compose.yml:

version: '3.8'
services:
  http-echo:
    image: mendhak/http-https-echo
    ports:
      - "8080:8080" # Map host port 8080 to container's HTTP port 8080
      - "8443:8443" # Map host port 8443 to container's HTTPS port 8443
    restart: unless-stopped

Stopping the Container

• Interactive Mode: If you ran the container with -it, press Ctrl+C.
• Detached Mode: If you ran it in the background with -d (or with Docker Compose), use docker stop <container_id> or docker-compose down.

Example Output

When a request hits the echo server, you’ll see a JSON object similar to this in your Docker logs. This detailed output allows you to confirm that your client applications are sending requests exactly as you intend.

[1] 2023-10-27T10:30:00.123Z  INFO    {
  "hostname": "127.0.0.1",
  "method": "GET",
  "path": "/some/path",
  "query": {
    "param": "value"
  },
  "headers": {
    "host": "localhost",
    "user-agent": "curl/7.68.0",
    "accept": "*/*",
    "x-custom-header": "test"
  },
  "body": {}
}