Mad World #Save_GAZA: Free Palestine  

Search

miniProxy: What It Is and How to Run It, Fixed for PHP 8 (Tested)

miniProxy: What It Is and How to Run It, Fixed for PHP 8 (Tested)

miniProxy is a free, open-source web proxy written in PHP: one file, miniProxy.php, that opens other websites for you through the server it runs on. Joshua Dick first released it in 2005 as PageForward, and he stopped maintaining it on 26 April 2020. That last version no longer works well: on PHP 8 and on today's large websites it shows PHP errors, garbled text and blank pages.

So we fixed it. On 12 November 2026 we ran the archived version in Docker, traced every problem we hit, and wrote a small patch for them. With the patch, a YouTube video plays through miniProxy, X shows its sign-in page, Wikipedia loads with all its images, and local addresses stay blocked. This guide gives you the three files we tested and every step, with screenshots from that test.

  • What it is: a one-file PHP web proxy under the GNU GPL v3, archived on GitHub since April 2020.
  • Does the original still work? Not on today's PHP and websites. On PHP 8.5 it prints "Deprecated" notices into its pages, Wikipedia ends in a PHP fatal error, and a YouTube video page never gets past an empty skeleton.
  • The fix: a Dockerfile, a compose.yaml and a patch file, tested with PHP 8.5.12, Apache 2.4.69 and Docker Engine 29.2.1.
  • The rule: keep it private, on 127.0.0.1 or behind a login. A public web proxy gets abused.

"Welcome to miniProxy!": what this page is

When you open the address of a miniProxy installation without a website after it, miniProxy shows its start page: the title Welcome to miniProxy!, the line miniProxy can be directly invoked like this: with an example address, a text field and a Proxy It! button.

miniProxy start page at 127.0.0.1:8080 with the Welcome to miniProxy text, the example address, the address field and the Proxy It button
The start page of our patched miniProxy, on the test computer.

If you meet this page on the internet, someone installed miniProxy on that server. The page itself does nothing harmful. But the owner of that server can see every page you open through it, and everything you type into those pages.

How miniProxy works, and the right miniProxy URL

miniProxy downloads the page you ask for with PHP's cURL extension. Then it rewrites the links, images, styles and forms of that page so that they also go through miniProxy, and it adds a small script that sends the page's own requests through miniProxy too. Your browser talks only to the miniProxy server. The miniProxy server talks to the website.

To open a page, type its address in the field and click Proxy It!. Or write the address directly after the address of the script and a question mark:

Code
http://127.0.0.1:8080/index.php?https://en.wikipedia.org/wiki/Proxy_server

Keep the name of the script in the address: index.php in our Docker setup, miniProxy.php if you copied the file under its own name. miniProxy finds the target address by cutting as many characters from the start of the path as the script name has. Without the name, it cuts too much: http://127.0.0.1:8080/?https://example.net opens xample.net, a different website. In our test, that address led to a page that sells the domain.

Why the original miniProxy breaks today

We first ran the last version unchanged, on the same official PHP 8.5 image with its default settings. Wikipedia stopped with a PHP fatal error, and a YouTube video page stayed empty:

Wikipedia opened through the unchanged miniProxy on PHP 8.5: Deprecated notices for curl_close() and mb_convert_encoding(), then Fatal error: Uncaught TypeError: implode()
The unchanged miniProxy on PHP 8.5: two "Deprecated" notices and a fatal error instead of the Wikipedia article.
YouTube video page through the unchanged miniProxy: an empty white page with only the menu icon and three grey circles
The video of Step 4 through the unchanged miniProxy: YouTube never gets past its empty page skeleton.

Then we fixed and retested it until Wikipedia, YouTube and X worked. Here is every problem we found, what you see in the browser, and what our patch changes. Each fix is a few lines, and the patch file explains each one in a comment.

  1. Deprecated functions. miniProxy calls curl_close(), deprecated in PHP 8.5, and converts pages to HTML-ENTITIES, deprecated in PHP 8.2. With the image's default PHP settings, "Deprecated" notices are printed into the pages. The patch removes curl_close(), which does nothing since PHP 8.0, keeps pages in UTF-8 (point 4), and turns on PHP's production settings, which log notices instead of printing them.
  2. A fatal error on responsive images. implode() gets its arguments in the old order, which PHP 8 removed. Pages with responsive images, such as Wikipedia, end in a PHP fatal error. The patch puts the arguments in the right order.
  3. Broken images on phones and sharp screens. srcset image addresses lose their first /. The patch keeps each address as it is.
  4. Garbled text. Pages are converted to HTML-ENTITIES, and a page without a charset tag is read as ISO-8859-1. Text that a script shows, such as YouTube's titles, comes out as codes such as غ or as garbage letters. The patch keeps every page in UTF-8, and tells PHP's HTML parser so.
  5. Missing scripts and styles. The site's Content-Encoding: br or zstd header is passed on, after cURL already decoded the body, and the browser stops with ERR_CONTENT_DECODING_FAILED. The patch removes every Content-Encoding header.
  6. Requests that go around the proxy. The site's Content-Security-Policy header is passed on, so the browser blocks miniProxy's own script. The patch removes the Content-Security-Policy and Cross-Origin-* headers.
  7. YouTube's empty page skeleton. Only XMLHttpRequest is rerouted, and JSON bodies are read as a form, which empties them. The patch also reroutes fetch() and sendBeacon(), and sends other bodies unchanged.
  8. A video player that never loads. Scripts build addresses such as /s/player/…/base.js on the proxy's own address, which answers 404 Not Found. In the patched setup, Apache sends unknown paths to miniProxy, which finds the site from the page that asked (its Referer).
  9. A reload that opens a wrong page. Sites such as YouTube change the address in the address bar. The patch puts the index.php?site form back.
  10. "Is not valid JSON" errors. An empty answer ends in a PHP fatal error, and a PHP warning printed into an answer breaks the page's scripts. The patch skips empty pages, and production PHP settings log warnings instead of printing them.
  11. Local addresses that get through. The local-address filter misses localhost and 127.1: localhost opens pages of the proxy's own server, and 127.1 is requested before it is refused. The patch asks the system resolver too, and refuses a name that resolves to nothing.
  12. Redirects to local addresses. cURL follows redirects by itself, after the address was checked, so a public page can send the proxy to a local address. With the patch, the browser follows each redirect through the proxy, which checks every address.

Run the fixed miniProxy with Docker (tested)

Our test, on 12 November 2026: Docker Engine 29.2.1 with Docker Compose 2.29.7, the official php:8.5-apache image (PHP 8.5.12 and Apache 2.4.69), and miniProxy pinned to its last commit, 65cbed2. The container runs as the user www-data, drops all Linux capabilities, has a read-only root filesystem, and listens only on 127.0.0.1.

Step 1: create the three files

Make an empty folder, for example miniproxy, and create these three files in it.

Dockerfile: it downloads miniProxy, applies the patch, and turns on PHP's production settings.

Dockerfile
FROM php:8.5-apache

# miniProxy's last commit (27 April 2020): the project is archived, so the version is pinned.
ARG MINIPROXY_COMMIT=65cbed2907d16f0f25ecdabb420b44c83a36df08
ADD https://raw.githubusercontent.com/joshdick/miniProxy/${MINIPROXY_COMMIT}/miniProxy.php /var/www/html/index.php
COPY patch-miniproxy.php /tmp/

# PHP's production settings (errors go to the log, never into a page). Apache listens on 8080 so it runs without
# root, logs to "docker logs", and hands every unknown path to miniProxy. The patch stops the build if a fix fails.
RUN cp "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \
 && sed -i 's/^Listen 80$/Listen 8080/' /etc/apache2/ports.conf \
 && sed -i 's/<VirtualHost \*:80>/<VirtualHost *:8080>/; s#ErrorLog .*#ErrorLog /proc/self/fd/2#; s#CustomLog .*#CustomLog /proc/self/fd/1 combined#' /etc/apache2/sites-available/000-default.conf \
 && echo 'FallbackResource /index.php' > /etc/apache2/conf-available/miniproxy.conf \
 && a2enconf miniproxy \
 && php /tmp/patch-miniproxy.php /var/www/html/index.php \
 && php -l /var/www/html/index.php \
 && chmod 644 /var/www/html/index.php \
 && rm /tmp/patch-miniproxy.php

USER www-data

compose.yaml:

YAML
services:
  miniproxy:
    build: .
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=16m
      - /var/run/apache2:rw,noexec,nosuid,size=1m
      - /var/lock/apache2:rw,noexec,nosuid,size=1m

patch-miniproxy.php: each fix replaces one exact piece of the original file. If a fix does not find its piece exactly once, the build stops with the name of that fix. So a changed download can never give you a half-patched proxy.

PHP
<?php
// Fixes miniProxy's last version (commit 65cbed2, April 2020) for PHP 8 and for today's websites.
// Usage: php patch-miniproxy.php miniProxy.php   (the file is changed in place; the build stops if a fix does not apply)
$file = $argv[1] ?? 'miniProxy.php';
$code = file_get_contents($file);

$fixes = [
    // Pages are kept in UTF-8. The old HTML-ENTITIES conversion is deprecated since PHP 8.2, and it turned every
    // non-ASCII letter inside scripts into text like "&#1594;" (YouTube's titles came out unreadable).
    'utf-8' => [
        <<<'OLD'
    $responseBody = mb_convert_encoding($responseBody, "HTML-ENTITIES", $detectedEncoding);
OLD,
        <<<'NEW'
    $responseBody = mb_convert_encoding($responseBody, "UTF-8", $detectedEncoding);
    $responseBody = preg_replace('/(<meta\b[^>]*charset\s*=\s*["\']?)[\w-]+/i', '${1}utf-8', $responseBody);
NEW,
    ],
    // DOMDocument reads a page without a charset declaration (YouTube has none) as ISO-8859-1.
    'utf-8 read' => [
        <<<'OLD'
  @$doc->loadHTML($responseBody);
OLD,
        <<<'NEW'
  @$doc->loadHTML('<?xml encoding="UTF-8">' . $responseBody);
  foreach (iterator_to_array($doc->childNodes) as $node) {
    if ($node->nodeType === XML_PI_NODE) $doc->removeChild($node);
  }
NEW,
    ],
    // A charset declaration first in <head> makes DOMDocument write UTF-8 instead of entities.
    'utf-8 write' => [
        <<<'OLD'
  echo "<!-- Proxified page constructed by miniProxy -->\n" . $doc->saveHTML();
OLD,
        <<<'NEW'
  $head = $xpath->query("//head")->item(0);
  if ($head) {
    $meta = $doc->createElement("meta");
    $meta->setAttribute("http-equiv", "Content-Type");
    $meta->setAttribute("content", "text/html; charset=utf-8");
    $head->insertBefore($meta, $head->firstChild);
  }
  header("Content-Type: text/html; charset=UTF-8", true);
  echo "<!-- Proxified page constructed by miniProxy -->\n" . $doc->saveHTML();
NEW,
    ],
    // PHP 8 removed implode()'s old argument order: every page with srcset images ended in a fatal error.
    'implode' => [
        'implode($components, " ")',
        'implode(" ", $components)',
    ],
    // PHP 8.5 deprecates curl_close(), which does nothing since PHP 8.0.
    'curl_close' => [
        '  curl_close($ch);
',
        '',
    ],
    // srcset addresses lost their first "/", so "//thumb.wikimedia.org/a.png" became a path of the page itself:
    // high-density screens (phones, laptops), which use srcset, showed broken images.
    'srcset' => [
        'rel2abs(ltrim($components[0], "/"), $baseURL)',
        'rel2abs($components[0], $baseURL)',
    ],
    // An address that starts with "//" takes the page's scheme (it was sent as http, then redirected to https).
    'scheme-relative' => [
        'if (parse_url($rel, PHP_URL_SCHEME) != "" || strpos($rel, "//") === 0) return $rel;',
        'if (strpos($rel, "//") === 0) return parse_url($base, PHP_URL_SCHEME) . ":" . $rel;
  if (parse_url($rel, PHP_URL_SCHEME) != "") return $rel;',
    ],
    // cURL has already decoded the body, so no Content-Encoding may be passed on (miniProxy only knew gzip; sites now
    // send br and zstd). The site's Content-Security-Policy and Cross-Origin policies would block miniProxy's own script.
    'headers' => [
        '"/^Content-Length|^Transfer-Encoding|^Content-Encoding.*gzip/i"',
        '"/^Content-Length|^Transfer-Encoding|^Content-Encoding|^Content-Security-Policy|^Cross-Origin-/i"',
    ],
    // The local-address filter missed "localhost" (DNS does not know it) and "127.1" (no DNS answer, but cURL opens
    // it as 127.0.0.1): ask the system resolver too, and refuse a name that resolves to nothing.
    'local names' => [
        <<<'OLD'
      $dnsResult = dns_get_record($host, DNS_A + DNS_AAAA);
      $ips = array_map(function($dnsRecord) { return $dnsRecord['type'] == 'A' ? $dnsRecord['ip'] : $dnsRecord['ipv6']; }, $dnsResult);
    }

OLD,
        <<<'NEW'
      $dnsResult = dns_get_record($host, DNS_A + DNS_AAAA) ?: [];
      $ips = array_map(function($dnsRecord) { return $dnsRecord['type'] == 'A' ? $dnsRecord['ip'] : $dnsRecord['ipv6']; }, $dnsResult);
      $ips = array_merge($ips, gethostbynamel($host) ?: []);
    }
    if (empty($ips)) {
      return true;
    }

NEW,
    ],
    // cURL followed redirects itself, so a public page that redirects to a local address reached it unchecked.
    // The browser now follows each redirect through the proxy, which checks every address before opening it.
    'redirects' => [
        'curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);',
        'curl_setopt($ch, CURLOPT_FOLLOWLOCATION, false);',
    ],
    'redirect address' => [
        '  if (!preg_match($header_blacklist_pattern, $header)) {',
        '  if (stripos($header, "Location:") === 0) {
    $header = "Location: " . PROXY_PREFIX . rel2abs(trim(substr($header, 9)), $url);
  }
  if (!preg_match($header_blacklist_pattern, $header)) {',
    ],
    // An empty HTML answer (a "204 No Content", for example) made DOMDocument stop with a fatal error since PHP 8.
    'empty page' => [
        'if (stripos($contentType, "text/html") !== false) {',
        'if (stripos($contentType, "text/html") !== false && $responseBody !== "") {',
    ],
    // A request without a port printed a PHP warning into the answer (a JSON answer then stops being JSON).
    'origin port' => [
        '$port = $urlParts["port"];',
        '$port = $urlParts["port"] ?? "";',
    ],
    // Apache's FallbackResource sends every other path of the proxy here, like "/s/player/base.js": a relative
    // address built by one of the page's scripts. It goes to the site of the page that asked for it (its Referer).
    'relative paths' => [
        '    $url = substr($_SERVER["REQUEST_URI"], strlen($_SERVER["SCRIPT_NAME"]) + 1);
',
        '    $url = substr($_SERVER["REQUEST_URI"], strlen($_SERVER["SCRIPT_NAME"]) + 1);
    $referer = $_SERVER["HTTP_REFERER"] ?? "";
    if (strpos($_SERVER["REQUEST_URI"], $_SERVER["SCRIPT_NAME"]) !== 0 && $_SERVER["REQUEST_URI"] !== "/" && strpos($referer, PROXY_PREFIX) === 0) {
      $site = parse_url(substr($referer, strlen(PROXY_PREFIX)));
      if (!empty($site["scheme"]) && !empty($site["host"])) {
        $url = $site["scheme"] . "://" . $site["host"] . (isset($site["port"]) ? ":" . $site["port"] : "") . $_SERVER["REQUEST_URI"];
      }
    }
',
    ],
    // A JSON or other non-form body is sent on as it is, instead of being parsed as a form (which emptied it).
    'post body' => [
        '      $postData = [];
      parse_str(file_get_contents("php://input"), $postData);
      if (isset($postData["miniProxyFormAction"])) {
        unset($postData["miniProxyFormAction"]);
      }
      curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));',
        '      $rawBody = file_get_contents("php://input");
      if (stripos($_SERVER["CONTENT_TYPE"] ?? "", "application/x-www-form-urlencoded") === false) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $rawBody);
      } else {
        $postData = [];
        parse_str($rawBody, $postData);
        unset($postData["miniProxyFormAction"]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
      }',
    ],
    // XMLHttpRequest, fetch() and sendBeacon() all go through toProxy() below, which also sends addresses a script
    // built from the proxy's own origin back to the real site. (No single quote, "&", "<" or ">" in this JavaScript:
    // it sits inside a PHP string that DOMDocument writes into a <script> element.)
    'xhr' => [
        '                var url = arguments[1];
                url = rel2abs("\' . $url . \'", url);
                if (url.indexOf("\' . PROXY_PREFIX . \'") == -1) {
                  url = "\' . PROXY_PREFIX . \'" + url;
                }
                arguments[1] = url;
',
        '                arguments[1] = toProxy(arguments[1]);
',
    ],
    'fetch' => [
        '              return proxied.apply(this, [].slice.call(arguments));
          };
',
        '              return proxied.apply(this, [].slice.call(arguments));
          };

          var proxyPrefix = "\' . PROXY_PREFIX . \'";
          var targetOrigin = "\' . parse_url($url, PHP_URL_SCHEME) . "://" . parse_url($url, PHP_URL_HOST) . (parse_url($url, PHP_URL_PORT) ? ":" . parse_url($url, PHP_URL_PORT) : "") . \'";
          function toProxy(target) {
            target = String(target);
            if (!target || target.indexOf(proxyPrefix) === 0 || /^(data|blob|about|javascript):/i.test(target)) return target;
            if (target.indexOf(location.origin + "/") === 0) target = targetOrigin + target.slice(location.origin.length);
            return proxyPrefix + rel2abs("\' . $url . \'", target);
          }
          if (window.fetch) {
            var proxiedFetch = window.fetch;
            window.fetch = function(input, init) {
              if (!(input instanceof Request)) return proxiedFetch.call(window, toProxy(input), init);
              // A Request copied with its body would send that body as a stream, which needs HTTP/2:
              // read the body first, then build the new Request.
              var original = input;
              var body = original.method === "GET" || original.method === "HEAD" ? Promise.resolve(null) : original.arrayBuffer();
              return body.then(function(data) {
                return proxiedFetch.call(window, new Request(toProxy(original.url), {
                  method: original.method, headers: original.headers, body: data, credentials: original.credentials,
                  cache: original.cache, redirect: original.redirect, keepalive: original.keepalive, signal: original.signal
                }), init);
              });
            };
          }
          if (navigator.sendBeacon) {
            var proxiedBeacon = navigator.sendBeacon.bind(navigator);
            navigator.sendBeacon = function(target, data) { return proxiedBeacon(toProxy(target), data); };
          }
          // Single-page sites (YouTube) rewrite the address bar: keep it in the "index.php?site" form,
          // so a reload still works and the next requests still say which site they belong to.
          ["pushState", "replaceState"].forEach(function(name) {
            var original = History.prototype[name];
            History.prototype[name] = function(state, title, address) {
              if (address === undefined || address === null) return original.call(this, state, title);
              return original.call(this, state, title, toProxy(address));
            };
          });
          // YouTube changes the address with a History method taken from another frame, which the hook above does not
          // see: put the "index.php?site" form back as soon as the address changes.
          if (window.navigation) {
            navigation.addEventListener("currententrychange", function() {
              if (location.href.indexOf(proxyPrefix) !== 0) history.replaceState(history.state, "", toProxy(location.href));
            });
          }
          // Images, scripts, styles and frames that scripts add later also load through the proxy.
          function proxyProperty(type, property) {
            var descriptor = type ? Object.getOwnPropertyDescriptor(type.prototype, property) : null;
            if (!descriptor || !descriptor.set) return;
            Object.defineProperty(type.prototype, property, {
              configurable: true, enumerable: descriptor.enumerable, get: descriptor.get,
              set: function(value) { descriptor.set.call(this, toProxy(value)); }
            });
          }
          proxyProperty(window.HTMLImageElement, "src");
          proxyProperty(window.HTMLScriptElement, "src");
          proxyProperty(window.HTMLLinkElement, "href");
          proxyProperty(window.HTMLIFrameElement, "src");
          proxyProperty(window.HTMLSourceElement, "src");
          proxyProperty(window.HTMLMediaElement, "src");
          var proxiedSetAttribute = Element.prototype.setAttribute;
          Element.prototype.setAttribute = function(name, value) {
            if (/^(src|href)$/i.test(name) && /^(img|script|link|iframe|source|video|audio)$/i.test(this.tagName)) value = toProxy(value);
            return proxiedSetAttribute.call(this, name, value);
          };
',
    ],
];

foreach ($fixes as $name => [$old, $new]) {
    $count = substr_count($code, $old);
    if ($count !== 1) {
        fwrite(STDERR, "miniProxy patch \"$name\": expected the original text once, found it $count times\n");
        exit(1);
    }
    $code = str_replace($old, $new, $code);
}
file_put_contents($file, $code);
echo 'miniProxy patched: ', implode(', ', array_keys($fixes)), "\n";

The patch is free software under the GNU GPL v3, like miniProxy itself.

Step 2: build and start it

In the folder that holds the three files, run:

Terminal
docker compose up -d --build
docker compose ps

Among the build lines, look for these two. They show that every fix applied and that the result is valid PHP:

Code
miniProxy patched: utf-8, utf-8 read, utf-8 write, implode, curl_close, srcset, scheme-relative, headers, local names, redirects, redirect address, empty page, origin port, relative paths, post body, xhr, fetch
No syntax errors detected in /var/www/html/index.php

docker compose ps then lists the miniproxy service as Up, on 127.0.0.1:8080.

Step 3: open a page through the proxy

Open http://127.0.0.1:8080/ in your browser: the start page appears. Type https://en.wikipedia.org/wiki/Proxy_server in the field and click Proxy It!.

Wikipedia's Proxy server article opened through miniProxy at 127.0.0.1:8080, with its images and its diagram
Wikipedia through the patched miniProxy, images included. The original stops here with a PHP fatal error.

Step 4: try YouTube and X

Open http://127.0.0.1:8080/index.php?https://www.youtube.com/. A visitor without an account and without a watch history gets YouTube's empty home page, Try searching to get started. We got the same page with the same browser through a normal forward proxy, so this is YouTube's choice, not a miniProxy problem.

YouTube home page through miniProxy showing Try searching to get started, with the Search field and the Sign in button
YouTube's home page through miniProxy, for a visitor with no history.

Search works: we typed me at the zoo and got the list of results, with the address still in the index.php?https://www.youtube.com/results?… form. Then open a video. In 8 test runs with the final patch, the video played every time: it was 3 seconds in, 10 to 15 seconds after the page opened.

YouTube video Me at the zoo playing in theater mode through miniProxy at 127.0.0.1:8080
"Me at the zoo" playing through miniProxy, at 11.9 of its 19 seconds when we took the picture.

X opens its sign-in page through miniProxy:

X sign-in page Happening now opened through miniProxy at 127.0.0.1:8080
x.com through miniProxy. You can read public pages, but signing in does not work (see the troubleshooting part).

Step 5: check that local addresses are refused

miniProxy must never open the pages of your own network: your router, your NAS, the server itself. Test it with three addresses:

Code
for u in http://localhost:8080/ http://127.1:8080/ http://192.168.1.1/; do
  curl -s "http://127.0.0.1:8080/index.php?$u"; echo
done

All three lines must say:

YAML
Error: The requested URL was disallowed by the server administrator.

With the original file, localhost got through and returned miniProxy's own start page, and 127.1 was refused only after the proxy had already requested it.

miniProxy refusing http://192.168.1.1/ with the message Error: The requested URL was disallowed by the server administrator
A local address refused by the patched miniProxy.

Step 6: stop and remove it

Terminal
docker compose down --rmi local

This stops the container and deletes the image that the build made.

Settings in miniProxy.php

All settings are PHP variables at the top of the file (/var/www/html/index.php in our image). These are the defaults of the last version:

  • $whitelistPatterns (default: empty): when it holds patterns, miniProxy opens only the addresses that match one of them.
  • $blacklistPatterns (default: empty): addresses that match a pattern here are refused.
  • $forceCORS (default: false): adds CORS (cross-origin resource sharing) headers to every answer.
  • $disallowLocal (default: true): refuses local and private addresses, so visitors cannot use the proxy to reach your own network.
  • $anonymize (default: true): does not send the visitor's IP address to the websites in an X-Forwarded-For header.
  • $startURL (default: empty): a page to open instead of the start page when no address is given.
  • $landingExampleURL (default: https://example.net): the example address on the start page.

To change a setting in the Docker setup, add one more line to the RUN step of the Dockerfile that edits /var/www/html/index.php after the patch. Keep $disallowLocal set to true.

Troubleshooting

Some HTTPS sites load forever

If YouTube, for example, never finishes loading through the proxy while other sites work, the container's network may send bigger packets than your connection carries. This happens on links with an MTU below 1500, such as some VPNs and PPPoE connections. Look at the mtu value of your main network interface with ip link. If it is below 1500, add this block at the end of compose.yaml, with a value no higher than that MTU:

YAML
networks:
  default:
    driver_opts:
      com.docker.network.driver.mtu: "1400"

Docker applies the MTU only when it creates the network, so recreate it:

Terminal
docker compose down
docker compose up -d

The video does not start

Reload the page. In our tests, when a video did not start, it played on the next try. Through miniProxy, YouTube's player also makes one extra request that YouTube refuses (400, "Precondition check failed"). In our tests the video still played, from the data in the page.

Signing in does not work

miniProxy passes the site's cookies on unchanged. Your browser refuses a cookie that names another domain, for example .x.com while the address bar shows 127.0.0.1, so a session never sticks. Use miniProxy for public pages.

A site still breaks

miniProxy rewrites pages and reroutes requests, but it cannot catch everything. Live connections (WebSocket), service workers and strict bot checks can still fail, and some images that a script loads from another domain go directly instead of through the proxy. For complete sites, use a forward proxy (see the alternatives below).

Security: keep miniProxy private

  • Never put it on the public internet. Open web proxies are found fast and used for abuse, and that abuse then comes from your server's IP address. Our compose.yaml publishes the port only on 127.0.0.1.
  • Need it on another device? Put a login in front of it: a VPN such as WireGuard or Tailscale, or a Cloudflare Tunnel with a Cloudflare Access policy. See how to create a Cloudflare Tunnel and expose your containers on Synology.
  • The local-address filter is a seat belt, not a wall. The patch closes the holes we found (localhost, 127.1, redirects). But the filter and cURL still look a name up separately, so a domain that changes its answer in between (DNS rebinding) could get through. Do not rely on the filter alone.
  • It does not make you anonymous. Websites see the server's IP address instead of yours, because miniProxy does not send X-Forwarded-For by default. But the server owner sees everything, and the author's README says it plainly: no web proxy can perfectly anonymize your web browsing.
  • Use it responsibly. Respect the terms of the sites you open (YouTube's terms forbid robots, scrapers and downloading without permission), the rules of the network you are on, and the law where you live. miniProxy is for a person who reads pages, not for scraping.

Alternatives to miniProxy

  • To reach your own home services from outside: a VPN (WireGuard, Tailscale) or a Cloudflare Tunnel.
  • A maintained forward proxy for your devices: Squid. You set it as the proxy in the browser or the system, and pages load unchanged. In our test, Squid 6.13 (the ubuntu/squid image) played the same YouTube video and opened X with no change to the sites. Tinyproxy is a smaller option.
  • A filtering, privacy-focused proxy: Privoxy.

Frequently asked questions

What does "Welcome to miniProxy!" mean?

It is the start page of a miniProxy installation. Someone runs miniProxy on that server, and the page waits for the address of a website to open through it.

Is miniProxy free?

Yes. miniProxy is open source under the GNU GPL v3, and our patch is under the same license.

Where can I download miniProxy.php?

From the joshdick/miniProxy repository on GitHub. The repository is archived, so the file there is the last version, with the problems listed above. Our Dockerfile downloads that exact version and patches it.

Does miniProxy work with YouTube?

The original does not: on PHP 8.5, a YouTube video page never gets past its empty skeleton. With our patch, search works and videos play: in 8 test runs with the final patch, the video played every time.

Does miniProxy work on PHP 8?

The original starts, but on PHP 8.5 it prints "Deprecated" notices into its pages, because it calls curl_close() (deprecated in PHP 8.5) and the HTML-ENTITIES conversion (deprecated in PHP 8.2). Pages with responsive images end in a fatal error. With the patch, it ran on PHP 8.5.12 in our test without a single PHP error in the log.

Is miniProxy safe?

On your own computer, bound to 127.0.0.1 as above, it is a good way to learn how a web proxy works. On a public server it is risky for you and for others. On someone else's server, you trust that person with everything you open.

Why does a site not load through miniProxy?

The site may refuse requests from servers, or need things that miniProxy cannot pass on: sign-in cookies, live connections, service workers. Check the troubleshooting part above, and see the README on GitHub for the author's own list of limits.

Running more containers at home? See how to install Portainer on a Synology NAS to manage them.

Sources

Yassine

Yassine

Yassine founded IGProd to educate the visitors with technological tutorials. These helpful guides are available for all sorts of professionals and novices, whether they work in technology or not!

Surf freely 💗

Leave a comment

Your email address will not be published. Required fields are marked *

Your experience on this site will be improved by allowing cookies Cookie Policy