web-proxy

web-proxy is a reverse proxy that gives production grade structured logs to web applications that were not built with observability in mind. Many popular frameworks log inconsistently, and some production builds drop logging entirely. NextJS and Prisma ORM are typical examples. Instead of editing application code, run web-proxy in front of the application. Every request is logged as structured JSON before it is forwarded upstream, so traffic becomes queryable in Grafana, Loki, and Promtail.

What a request looks like

When a client hits the proxy, web-proxy records the full picture of the exchange.

{
  "level": "info",
  "status": 200,
  "method": "GET",
  "URI": "/api/items?page=2",
  "route": "/api/items",
  "protocol": "HTTP/1.1",
  "remote_ip": "203.0.113.8",
  "host": "example.com",
  "referer": "https://example.com/home",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
  "id": "6f9c2ab7e4d84a2f",
  "latency": 2850000,
  "latency_human": "2.85ms",
  "bytes_in": 0,
  "bytes_out": 4182,
  "target": "http://localhost:3001"
}

Every log line carries the request ID, the client IP taken from the X-Forwarded-For header, the proxy target that served the request, and latency in nanoseconds plus a human readable form. Requests whose paths carry a file extension are logged separately from application routes, which keeps static asset noise easy to filter. Failed requests produce an error level line with the same fields plus the underlying error.

Features

• Structured JSON logs for every request with status, method, path, latency, bytes transferred, request ID, and real client IP.
• Reverse proxying to a single application or load balancing across several upstreams.
• TCP health checks that drop dead upstreams from rotation and answer 503 when every target is down.
• Static hosting for frontend builds.
• Managed mode that starts your web application and forwards public traffic to it.
• Access control through basic auth, bearer keys, or a branded session login page.
• Blocking of specific user agents and client IP addresses.
• Configuration through environment variables with safe defaults and .env support.

Quick start

npm

web-proxy ships as an npm package that downloads the matching binary during installation.

npm i @maxpeterkaya/web-proxy

Add the scripts below to package.json to let web-proxy run your application.

{
  "scripts": {
    "start:web": "next start",
    "start": "npx web-proxy -app"
  }
}

Start it with npm run start. web-proxy reads the start:web script, launches your app on an internal port, and serves it on PORT 3000 by default. Detailed setup and the concurrent alternative live in the Install Guide.

Docker

The container image vc.maxkaya.com/maxpeterkaya/web-proxy:latest runs web-proxy on its own. Wire it into a compose stack to log a sibling service.

services:
  proxy:
    image: vc.maxkaya.com/maxpeterkaya/web-proxy:latest
    ports:
      - "3000:3000"
    environment:
      PROXY_TARGETS: app:3001

  app:
    image: your-app:latest
    expose:
      - "3001"

Replace your-app with your own image and match the service name and port to your stack.

Binary

Release binaries are published for Linux, macOS, FreeBSD, OpenBSD, and NetBSD across amd64, arm, and arm64. The Install Guide covers every way to obtain web-proxy.

Run modes

| Mode | Invocation | What it does | | --- | --- | --- | | Managed app | web-proxy -app | Starts your application from package.json and proxies public traffic to it | | Reverse proxy | web-proxy | Forwards PORT to an upstream application on PROXY_PORT | | Load balancer | web-proxy with PROXY_TARGETS set | Distributes requests across upstreams that pass health checks | | Static site | web-proxy -static | Serves the frontend build in -static-dir |

Container deployments can wrap an existing image as middleware inside the application container or as a separate proxy container. See the container middleware and container proxy examples for those setups.

Configuration

web-proxy is configured through environment variables and honors a .env file in the working directory. Every variable has a default, so the proxy runs without any setup. The Usage Guide contains the complete variable reference.

Examples

• Container middleware
• Container proxy
• Load balancer
• Static website
• Authentication

Roadmap

These items are in no particular order.

• Screenshots
• Benchmarks
• Configurable logs
• Templates

License

web-proxy is released under the Apache License 2.0.