go-httpbin on AWS User Guide

Overview

This image runs go-httpbin, the fast, dependency free HTTP request and response testing service, a Go implementation of the well known httpbin. It exposes a rich set of endpoints for exercising and debugging anything that speaks HTTP: echo endpoints such as /get, /post, /put and /delete that reflect the method, headers, query arguments and body of your request back to you as JSON; status code endpoints such as /status/{code} that return any HTTP status you ask for; and utility endpoints for headers, client IP, redirects, delays, streaming, gzip and deflate responses, basic auth challenges, cookies, UUIDs and random bytes. The image is delivered as a ready-to-use appliance: a working test endpoint is answering requests within minutes of launch.

go-httpbin is the tool you point your HTTP clients, SDKs, proxies, API gateways, load balancers and CI pipelines at when you need a predictable, controllable server on the other end. Want to verify your client handles a 429 with a Retry-After header, a slow response, a chunked stream, or a redirect chain correctly? go-httpbin gives you an endpoint for each, with no external dependencies and no shared public rate limits to fight.

This is a headless service with no web console to log in to. It is secure by default: go-httpbin has no authentication of its own and its redirect and fetch endpoints could be abused as an open reflector, so this image never exposes it directly. go-httpbin binds the loopback interface only (127.0.0.1:8080), and nginx is the single network facing surface. nginx terminates TLS on port 443 with a per instance self signed certificate and fronts the entire service with HTTP basic authentication, while an unauthenticated health endpoint is available for load balancer probes and plain HTTP on port 80 redirects to HTTPS.

Nothing secret is baked into the image. On the first boot of your instance a one-shot service generates a unique HTTP basic authentication password for the user httpbin and a unique self signed TLS certificate, then writes them to the root-only file /root/go-httpbin-credentials.txt.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and ports 80 and 443 from your clients
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for go-httpbin. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and ports 80 and 443 from your clients. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass; the per instance TLS certificate and basic auth password are generated and the service is serving over HTTPS by the time you can connect.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg go-httpbin Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network and ports 80 and 443 from your clients.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=go-httpbin}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Step 4: Retrieve the Per Instance Credentials

The HTTP basic auth password and the TLS certificate are unique to your instance and generated on first boot. Read the credentials file, which is readable only by root:

sudo cat /root/go-httpbin-credentials.txt

You will see the username (httpbin), the generated password, and the service URL. Keep this file secret. If you ever need to rotate the password, regenerate the htpasswd entry at /etc/nginx/go-httpbin.htpasswd and reload nginx.

Step 5: Confirm the Service Is Running

go-httpbin runs as a hardened systemd service bound to loopback only, with nginx as the sole network facing surface. Confirm both services are active and that go-httpbin is listening only on 127.0.0.1:8080:

systemctl is-active go-httpbin nginx

sudo ss -ltnp | grep -E '127.0.0.1:8080|:443'

The first command prints active for both units. The second shows go-httpbin listening on 127.0.0.1:8080 (loopback only, never exposed to the network) and nginx listening on port 443.

Step 6: Verify the Security Posture

The service is never an open reflector. An unauthenticated request is rejected with 401, while the health endpoint stays open for load balancer probes. Verify both directly on the instance:

curl -sk -o /dev/null -w 'unauthenticated /get -> %{http_code}\n' https://127.0.0.1/get

curl -sk https://127.0.0.1/healthz

The first command prints 401. The second prints ok (the unauthenticated /healthz probe). Plain HTTP on port 80 redirects to HTTPS.

Step 7: Exercise the API

With the per instance basic auth credentials, the echo endpoints reflect your request back as JSON. The block below reads the generated password from the credentials file into a shell variable at runtime, so no secret is ever typed on the command line, then exercises a few representative endpoints locally on the instance:

PW=$(sudo grep '^GO_HTTPBIN_PASSWORD=' /root/go-httpbin-credentials.txt | cut -d= -f2-)
curl -sk -u "httpbin:$PW" "https://127.0.0.1/get?project=cloudimg" | head -20
curl -sk -o /dev/null -w '/status/418 -> %{http_code}\n' -u "httpbin:$PW" https://127.0.0.1/status/418
curl -sk -u "httpbin:$PW" https://127.0.0.1/json | head -12

/get echoes the method, headers and query arguments of your request as JSON, /status/418 returns the exact HTTP status code you asked for, and /json returns a sample document.

Step 8: Use It from Your Own Clients

From your workstation, your test suite or a CI job, point any HTTP client at the HTTPS endpoint with the basic auth user and password from Step 4. The TLS certificate is per instance self signed, so pass -k (or install the certificate) until you front the service with your own domain and a trusted certificate.

# Echo endpoints reflect your request back as JSON
curl -k -u httpbin:<password> https://<public-ip>/get
curl -k -u httpbin:<password> -X POST -d 'hello=world' https://<public-ip>/post

# Ask for any HTTP status code to test error handling and retries
curl -k -u httpbin:<password> https://<public-ip>/status/429

# Add a delay to test timeouts, or stream a response to test backpressure
curl -k -u httpbin:<password> https://<public-ip>/delay/3
curl -k -u httpbin:<password> https://<public-ip>/stream/10

# Inspect headers, client IP, redirects, cookies and encodings
curl -k -u httpbin:<password> https://<public-ip>/headers
curl -k -u httpbin:<password> https://<public-ip>/ip
curl -k -u httpbin:<password> https://<public-ip>/gzip

Step 9: Front It with Your Own Domain and Certificate (Optional)

For production use, put go-httpbin behind your own hostname and a trusted TLS certificate. Point a DNS record at the instance, then either install a certificate from your certificate authority into /etc/nginx/tls/ and reload nginx, or terminate TLS at a load balancer in front of the instance. The nginx site is at /etc/nginx/sites-available/cloudimg-go-httpbin. cloudimg engineers can help you wire this up after purchase.

Security Notes

• go-httpbin binds 127.0.0.1:8080 only and is never exposed to the network directly. nginx on port 443 is the sole network facing surface.
• The whole service is behind per instance HTTP basic authentication, so its redirect and fetch endpoints cannot be abused as an SSRF or open redirect relay.
• No shared or default credentials ship in the image. The per instance password and TLS certificate are both generated on first boot.
• Keep /root/go-httpbin-credentials.txt secret. Restrict the instance security group to the clients that need access.

Support

cloudimg provides 24/7 technical support for this go-httpbin product by email at support@cloudimg.co.uk and via live chat. We help with deployment and first boot configuration, retrieving and rotating the per instance credentials, fronting the service with your own domain and a trusted TLS certificate, wiring go-httpbin into your HTTP client, SDK and CI test suites, using the status code, delay, streaming and encoding endpoints to test retries, timeouts and error handling, tuning request and response limits, go-httpbin version upgrades and patch guidance, and performance troubleshooting. Critical issues receive a one hour average response time.