This page covers every way to install and run web-proxy. See Home for a high level overview and Usage for the full option reference.

npm package

npm i @maxpeterkaya/web-proxy

Installation downloads the binary that matches your platform and marks it executable. The binary is pulled at install time, so the npm package always brings the latest release without manual version management.

Run your app through web-proxy

Add the following scripts to package.json.

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

Then run npm run start. web-proxy reads the start:web script, starts your app on the internal proxy port, and exposes it on the public port. The proxy accepts public traffic on PORT 3000 and talks to the app on PROXY_PORT 3001. A NextJS start command automatically gets the right port appended. For another framework make sure it listens on PROXY_PORT, or set PROXY_TARGETS to point at a different location.

Run your app and web-proxy concurrently

When you want to keep your own process manager, run web-proxy next to your app with concurrently.

npm i concurrently

{
  "scripts": {
    "start:proxy": "npx web-proxy",
    "start:web": "next start -p 3001",
    "start": "concurrently --prefix none \"npm run start:web\" \"npm run start:proxy\""
  }
}

The app must listen on the proxy target port, PROXY_PORT 3001 by default, so the example pins NextJS there. You can read the concurrently documentation here.

Container image

The image vc.maxkaya.com/maxpeterkaya/web-proxy:latest runs the proxy on its own. It is built for linux amd64, arm64, and armv7, and runs from a scratch base with only the proxy binary and CA certificates.

Wire the image into a compose stack to log or protect a sibling service. Set PROXY_TARGETS to the service name and port of the upstream, remembering that some tools prepend the stack name to service hostnames.

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

Two container patterns are covered in the examples. The container proxy example runs web-proxy as a separate container in front of another service, while the container middleware example embeds web-proxy in the same container as your application.

Binary downloads

Prebuilt binaries are published for Linux, macOS, FreeBSD, OpenBSD, and NetBSD on amd64, arm, and arm64. Each artifact is named web-proxy_<os>_<arch>. The containers and npm package both wrap these binaries, so the binary is useful for embedding web-proxy in a custom base image or running it directly on a host.

Next steps

For the configuration reference and run modes, see the Usage Guide.