Config Reference

A BareProxy config is one file. A line in the first column opens a block (global, site or pool), and the indented lines under it belong to it. Blocks don’t nest, and the whole grammar fits on one page.

A static site served over HTTPS needs three lines:

site example.com
  tls auto
  route /* -> files /var/www/example/public

tls auto gets a certificate for the name from Let’s Encrypt or any ACME CA on first use, keeps it in the state folder and renews it 30 days before it expires. An HTTPS site with no tls line does the same. To use your own files, write tls CERT KEY. A wildcard (*.example.com) or catch-all (*) site always needs certificate files, and bareproxy check names the line when they’re missing. In a global block, acme-email gives the certificate authority a contact address and acme-ca names another ACME directory. A site written as http://example.com serves plain HTTP and needs no certificate.

This is a complete config for a site served from a folder, with an API behind it and a www redirect. It names certificate files, so its line numbers match the demo:

# /etc/bareproxy/bareproxy.conf
site example.com
  tls /etc/bareproxy/example.com.crt /etc/bareproxy/example.com.key
  error 404 /404.html
  route /healthz -> respond 200 "ok"
  route /api/* -> api strip
  route /* -> files /var/www/example/public

site www.example.com
  tls /etc/bareproxy/example.com.crt /etc/bareproxy/example.com.key
  route /* -> redirect 301 https://example.com

pool api
  backend 10.0.0.11:8080
  backend 10.0.0.12:8080
  backend 10.0.0.13:8080
  health /healthz

What It Does

  • site example.com serves HTTPS on port 443 with the certificate named by tls, and redirects plain http:// requests on port 80 to https://.
  • /healthz is answered by BareProxy itself, so a monitor can check the server without touching the application.
  • Everything under /api/ goes to pool api with the prefix stripped: /api/orders reaches the backend as /orders.
  • Everything else is served from /var/www/example/public, the site’s build output. /about/ serves about/index.html, and /about redirects to /about/.
  • error 404 /404.html names the site’s 404 page. It’s used for pages BareProxy can’t find, never in place of a backend’s own 404.
  • www.example.com redirects to a bare origin, so the path and query are kept. Both sites use one certificate, which has to cover both names.
  • Pool api checks each backend with GET /healthz every 5 seconds.

Rules

route [METHODS] PATH [header NAME[=VALUE]]... -> ACTION

  • /* matches every path. /api/* matches /api, /api/ and everything below it, never /apiv2. A path without /* matches only itself.
  • Methods are optional: route GET,HEAD /assets/* -> web.
  • header X-Beta needs the header present; header X-Beta=1 needs that value.
  • The action is files FOLDER, a pool name (add strip to drop the prefix), redirect CODE URL, or respond STATUS [TEXT].

Static Files

  • Folders are never listed. A folder without index.html is a 404.
  • Names that start with a dot, such as .git or .env, are never served, except under /.well-known/.
  • Nothing outside the folder is reached, whether through .., encoded escapes or symlinks. Relative symlinks that stay inside the folder work.
  • Precompressed copies such as app.js.br and app.js.gz are sent to clients that accept them. Nothing is compressed at run time.
  • ETag, Last-Modified, conditional requests, byte ranges and HEAD work the way HTTP says they should.

Commands

Command What it does
bareproxy run Starts the server in the foreground.
bareproxy check Checks the config file. Needs no running server.
bareproxy plan Shows what the file would change, compared with the running config. With --from FILE it compares two files and needs no server.
bareproxy apply Checks again, shows the plan, asks, and swaps the config in at once. With --plan ID it refuses if anything changed since that plan was made.
bareproxy rollback Makes the previous version live, or any version in the history.
bareproxy history Lists the last 100 versions: number, time, how it went live, Unix user and plan ID.
bareproxy explain Shows how a request would be handled, without sending it.
bareproxy why Tells the story of a request that already happened.
bareproxy tail Follows request records as they happen, with filters such as status>=500 or pool=api.
bareproxy status Listeners, sites, backends, certificates and recent error rates.
bareproxy events Recent changes in BareProxy’s own state: applies, reloads, certificates, and backends going up and down.
bareproxy version Prints the version and the Go version it was built with.

The config file is the source of truth. After every apply or rollback it holds exactly the running config, so a restart never changes behavior. If the file is broken at startup, BareProxy runs the last good version from the history and says so. A SIGHUP applies the file without asking, and keeps the running config if the file has errors.