How to Use BunkerWeb: The Beginner’s Guide to the Open-Source WAF
CodexFuse Team · 2026-11-02T13:29:26.657Z · 14 min read min read
BunkerWeb is the open-source WAF that sits in front of your apps and blocks OWASP attacks, bad bots, and known bad IPs by default. This beginner’s guide covers the Docker install, the protection lesson, reverse-proxying a real app, and Let’s Encrypt.
What Is BunkerWeb, Exactly?
Learning how to use BunkerWeb starts with one sentence. The vendor's own definition: "BunkerWeb is a next-generation, open-source Web Application Firewall (WAF)" (github.com/bunkerity/bunkerweb). You run it as a Docker container, and it sits in front of your applications — every request to your site passes through it first, and it blocks OWASP Top 10 attacks, bad bots, and known bad IPs before they reach your app.
The mental model that makes BunkerWeb click: it is a protective reverse proxy, and it is built on NGINX — "because BunkerWeb is based on the NGINX web server" (docs.bunkerweb.io/quickstart-guide/). So BunkerWeb is not a replacement for, or a rival of, the web server: it IS NGINX with a full security layer wrapped around it, plus a web UI for managing everything. Everything about BunkerWeb is configured with NAME=value settings passed as environment variables, from the domain it serves to the protections it applies. If you have never run it before, our Docker beginner guide covers the tooling you need; if your threat model also includes intrusion detection at the host level, our CrowdSec beginner guide is the natural companion — CrowdSec is an intrusion-prevention system, BunkerWeb is a WAF, and they are different layers, not rivals.
If you searched "bunkerweb tutorial", "bunkerweb docker", or "bunkerweb install", you are in the right place. This guide takes you from a zero-install state to a hardened, HTTPS-enabled deployment in seven steps: first deploy, the protection lesson, your first real app, Let's Encrypt, and the hardening arc. Facts here were verified against the vendor docs and the BunkerWeb GitHub repository on 2026-11-02, and versions or star counts move — treat them as snapshots.
How Do You Use BunkerWeb, Step by Step?
The shortest honest answer to "how to use bunkerweb" is this arc. Follow it in order and you will have a protected, HTTPS-served app in under an hour.
- Install Docker and create a network. BunkerWeb ships as a Docker image; your apps join its network so it can reach them.
- Run your first deploy. One
docker runcommand starts BunkerWeb serving a hello-world app. - Learn the settings model. Every setting is a
NAME=valueenvironment variable —SERVER_NAME,USE_REVERSE_PROXY,AUTO_LETS_ENCRYPT. - Watch it protect you. BunkerWeb's default policies block bad behavior out of the box — verify it by reading the logs and bans.
- Open the Web UI. The optional dashboard on port 7000 shows requests, bans, and blocked attacks.
- Put a real app behind it. Point
REVERSE_PROXY_HOSTat your service and keep your app on a private network. - Enable Let's Encrypt, then harden. One variable turns on free HTTPS; blacklist lists and an optional anti-bot challenge complete the arc.
How Do You Install and Run BunkerWeb for the First Time?
The answer: create a Docker network, then run the BunkerWeb image with your domain as an environment variable. The vendor's quickstart (docs.bunkerweb.io/quickstart-guide/) uses this form — shown here with the current stable tag, 1.6.17 (releases page, snapshot 2026-11-02):
docker network create bw-net docker run -d --name mybunker \ --network bw-net \ -p 80:8080 -p 443:8443 \ -v bw-data:/data \ -e SERVER_NAME=www.example.com \ -e USE_REVERSE_PROXY=yes \ -e REVERSE_PROXY_URL=/ \ -e REVERSE_PROXY_HOST=http://myapp \ bunkerity/bunkerweb:1.6.17
What each part does is worth knowing before you press enter, because these four pieces are the whole BunkerWeb install model:
| Part | What it does | Beginner note |
|---|---|---|
--network bw-net | Puts BunkerWeb on a shared Docker network | Your apps must join this same network so the proxy can reach them |
-p 80:8080 -p 443:8443 | Maps host ports 80/443 to the container's 8080/8443 | BunkerWeb listens on 8080/8443 inside the container, not 80/443 |
-v bw-data:/data | Persists configuration and state | Without it, a container restart wipes your setup |
-e SERVER_NAME=... | Declares which domain this instance serves | Every behavior BunkerWeb has is driven by settings like this one |
On Linux you can also keep your variables in a variables.env file and pass it with --env-file instead of a long -e chain — the quickstart documents both forms. Most beginners run this on a cheap VPS; if that term is new to you, our what VPS hosting is guide explains the hosting shape most small self-hosted deployments use.
What Does BunkerWeb Block by Default?
The protection lesson: BunkerWeb is secure out of the box — most of its security features are ON the moment the container starts. The vendor's own "Security features" list (github.com/bunkerity/bunkerweb) reads like a checklist of what you would otherwise pay an appliance vendor for:
| Protection | Vendor's words | Default |
|---|---|---|
| ModSecurity + OWASP CRS | "Integrated ModSecurity WAF with the OWASP Core Rule Set" | ON (USE_MODSECURITY=yes, USE_MODSECURITY_CRS=yes) |
| HTTPS + TLS hardening | "HTTPS support with transparent Let's Encrypt automation" and "State-of-the-art web security: HTTP security headers, prevent leaks, TLS hardening" | ON when enabled |
| Bad-behavior bans | "Automatic ban of strange behaviors based on HTTP status codes" | ON — 10 bad codes in 60 seconds earns a 24-hour ban |
| Rate limits | "Apply connection and request limits for clients" | ON (USE_LIMIT_REQ=yes) |
| IP blacklists + DNSBL | "Block known bad IPs with external blacklists and DNSBL" | ON — blocklists include bl.blocklist.de, sorbs, and spamhaus |
| BunkerNet | Collective-threat-intelligence feed from the BunkerWeb network | ON (USE_BUNKERNET=yes) |
| Anti-bot challenge | "Block bots by asking them to solve a challenge (e.g., cookie, JavaScript, captcha, hCaptcha, or reCAPTCHA)" | OFF — USE_ANTIBOT=no by default; USE_ANTIBOT=captcha turns it on |
Three beginner traps hide in that table. First, ModSecurity is a built-in, always-on component of BunkerWeb — so "bunkerweb vs modsecurity" is not a real rivalry; one contains the other, say it once. Second, the anti-bot challenge is the one headline feature that is OFF by default, so do not assume bots are being challenged until you enable it. Third, the vendor's concepts page states the settings model plainly: "Each setting is identified by a name such as AUTO_LETS_ENCRYPT or USE_ANTIBOT. You can assign values to the settings to configure BunkerWeb" (docs.bunkerweb.io/latest/concepts/).
How Do You See What BunkerWeb Blocked?
The answer: blocked requests surface in two places — the container logs and the Web UI. For a quick check, run docker logs mybunker: NGINX access and error lines reach the container logs promptly, so rejected requests appear there. For the full picture, enable the optional Web UI and open it in a browser.
The Web UI is a separate Flask application: "Default listener: 0.0.0.0:7000 in containers, 127.0.0.1:7000 in packages" (docs.bunkerweb.io/latest/web-ui/). The first run walks you through a setup wizard where you create the local admin account (password policy enforced, optional TOTP two-factor), and you can also preseed the credentials with ADMIN_USERNAME and ADMIN_PASSWORD environment variables. Inside you get dashboards for requests, bans, cache, and jobs, a view of blocked attacks with logs, and the ability to edit settings, restart, reload, and install plugins. A fast way to see the protection lesson working: request a nonsense URL that returns 404s repeatedly — once you pass 10 bad status codes in 60 seconds, USE_BAD_BEHAVIOR bans your IP for 24 hours, and the ban shows up in the UI's Bans dashboard.
How Do You Put a Real App Behind BunkerWeb?
The answer: keep your app on the shared Docker network and set USE_REVERSE_PROXY=yes plus REVERSE_PROXY_HOST to the app's internal address. BunkerWeb then forwards public traffic to your app while shielding it with every default protection. A typical first-real-app block looks like this:
-e USE_REVERSE_PROXY=yes \ -e REVERSE_PROXY_URL=/ \ -e REVERSE_PROXY_HOST=http://myapp:3000
The three settings each do one job in the bunkerweb reverse proxy flow: USE_REVERSE_PROXY=yes turns proxying on, REVERSE_PROXY_URL=/ maps the public root path, and REVERSE_PROXY_HOST is the internal address of your service — the container name works because both containers share bw-net. Do not publish your app's own port to the host: the app should be reachable only through BunkerWeb, so attackers never bypass the WAF. Serving several domains from one instance is the multisite mode: MULTISITE=yes, then per-site settings prefixed with the domain, for example app1.example.com_REVERSE_PROXY_HOST=http://myapp1 (docs.bunkerweb.io/latest/concepts/).
How Do You Enable Let's Encrypt in BunkerWeb?
The answer: set AUTO_LETS_ENCRYPT=yes and EMAIL_LETS_ENCRYPT to your contact address, and BunkerWeb obtains and renews the certificate automatically — the whole bunkerweb letsencrypt integration is one setting. The standard HTTP-01 challenge needs two things from you: DNS for your domain must point at the BunkerWeb server, and ports 80 and 443 must be reachable from the internet — this is why you test Let's Encrypt against a real domain, never localhost.
-e AUTO_LETS_ENCRYPT=yes \ -e [email protected]
Two useful variations: USE_LETS_ENCRYPT_STAGING=yes points at the staging CA while you test, so you never burn your production rate limits, and since version 1.6 BunkerWeb has Let's Encrypt DNS-01 challenge support built into the core, which matters when ports 80/443 cannot be opened. Note that AUTO_LETS_ENCRYPT defaults to no and is documented in a multisite context — set it alongside your SERVER_NAME and confirm the certificate appears before you announce the URL anywhere.
How Do You Harden BunkerWeb Beyond the Defaults?
The hardening arc has three moves: custom blacklists, the anti-bot challenge, and knowing when the HA setup applies. The blacklist settings are space-separated lists, and the vendor's settings page documents them exactly: BLACKLIST_IP — "List of IP/network, separated with spaces, to block" — with its mirror image WHITELIST_IP — "List of IP/network, separated with spaces, to whitelist". Out of the box USE_BLACKLIST=yes, with defaults like the Tor exit-node list at BLACKLIST_IP_URLS and Shodan/Censys reverse-DNS entries in BLACKLIST_RDNS; you can add BLACKLIST_COUNTRY, BLACKLIST_ASN, BLACKLIST_USER_AGENT, and BLACKLIST_URI for finer control.
-e BLACKLIST_IP="203.0.113.50 198.51.100.0/24" \ -e BLACKLIST_USER_AGENT="EvilBot/1.0" \ -e USE_ANTIBOT=captcha
The anti-bot challenge is the strongest single hardening move for bot-plagued sites, but remember it is OFF by default — USE_ANTIBOT=captcha makes suspicious clients solve a challenge before reaching your app. Bans (including the 24-hour bad-behavior bans) can be reviewed and lifted from the Web UI's Bans dashboard. The third move, high-availability clustering, is an advanced deployment documented in the vendor's own guides (undercodetesting.com's 292-day HA-cluster deep-dive is a feature deep-dive, not a beginner arc) — a single-container deploy with the defaults above is the correct starting point, and HA becomes relevant only when you need to survive a node's failure. For a confidence boost, the project keeps a demo at demo.bunkerweb.io that "invites visitors to attack it" (blog.whiteravens.net, October 7, 2026) — watching the WAF block live attacks is the fastest way to learn what the rules do.
BunkerWeb vs ModSecurity, Nginx, and CrowdSec: What Is the Real Difference?
The honest comparison that covers every "bunkerweb vs modsecurity" search: there is no rivalry in any of these pairings, because the relationships run one way. One line each, said once:
| Pairing | The real relationship |
|---|---|
| BunkerWeb vs ModSecurity | ModSecurity is BUILT INTO BunkerWeb and ON by default (USE_MODSECURITY=yes + OWASP CRS) — comparing them is like comparing a car to its engine |
| BunkerWeb vs Nginx | BunkerWeb IS Nginx-based ("because BunkerWeb is based on the NGINX web server") — it sits in front of your apps, not in place of a plain web server you would hand-configure |
| BunkerWeb vs CrowdSec | CrowdSec is an optional INTEGRATION (USE_CROWDSEC=yes, embedded in the all-in-one image) — WAF vs intrusion prevention, different layers that complement each other |
If you want the web-server layer explained from the ground up before adding the WAF layer, our Nginx beginner guide covers that foundation. The key takeaway: BunkerWeb's value is not any single one of these components — it is having ModSecurity, the OWASP rule set, bot challenges, blacklists, rate limits, and automatic HTTPS shipped as one configured container.
7 Beginner Mistakes That Break a BunkerWeb Deploy
Beginners hit the same seven walls, and every one of them is a configuration misunderstanding rather than a bug:
| Mistake | What happens | Fix |
|---|---|---|
| App not on the shared network | 502 Bad Gateway on every request | Start your app container with --network bw-net |
| Publishing the app's own port to the host | Attackers bypass the WAF entirely | Keep the app port internal; expose only 80/443 through BunkerWeb |
| Let's Encrypt on a local/test domain | Certificate issuance fails silently | DNS must resolve to the server and ports 80/443 must be open; use USE_LETS_ENCRYPT_STAGING=yes while testing |
| Assuming the anti-bot challenge is on | Bots pass straight through | USE_ANTIBOT defaults to no — set USE_ANTIBOT=captcha explicitly |
| Locking yourself out with a blacklist | Your own IP gets blocked | Add your IP to WHITELIST_IP before adding broad BLACKLIST_IP ranges |
| Following the docs' pinned 1.4.0 tag | You run an outdated release | Use the current stable tag (1.6.17 at the time of writing) — check the releases page |
| Skipping the volume mount | Restarting the container wipes config and state | Always mount -v bw-data:/data |
Sources
Every fact in this guide was fetched from its source on 2026-11-02. Versions and star counts move — treat them as snapshots of that date.
- github.com/bunkerity/bunkerweb — vendor self-description ("BunkerWeb is a next-generation, open-source Web Application Firewall (WAF)"), AGPL-3.0 license field, security-features list verbatims, 11,206 stars (snapshot)
- github.com/bunkerity/bunkerweb/releases — latest stable 1.6.17, pre-releases 1.6.18-rc1/rc2 (snapshot)
- docs.bunkerweb.io/quickstart-guide/ — hello-world docker run form, variables.env form, reverse-proxy settings, NGINX-under-the-hood fact
- docs.bunkerweb.io/settings/ — exact defaults for USE_MODSECURITY, USE_BAD_BEHAVIOR, USE_BLACKLIST, BLACKLIST_*/WHITELIST_* names, AUTO_LETS_ENCRYPT, EMAIL_LETS_ENCRYPT, USE_LETS_ENCRYPT_STAGING
- docs.bunkerweb.io/latest/concepts/ — settings NAME=value model, multisite domain-prefix form
- docs.bunkerweb.io/latest/web-ui/ — UI listener 0.0.0.0:7000 in containers, admin auth, setup wizard, dashboards
- blog.whiteravens.net/2026/10/07 — "BunkerWeb: NGINX, ModSecurity and Bot Filtering in One Reverse Proxy" (October 7, 2026 independent overview, explainer not a hands-on walkthrough; demo.bunkerweb.io invite-to-attack)
- undercodetesting.com — BunkerWeb HA-cluster deep-dive (292 days old, advanced) and blacklisting deep-dive (311 days old, feature deep-dives, not beginner arcs)
- computingforgeeks.com — BunkerWeb Docker run guide (1226 days old, stale)
- wafplanet.com — "Best WAF for Docker" comparison list (~107 days old)
Frequently Asked Questions
Is BunkerWeb free to use?
Yes — BunkerWeb is open source under the AGPL-3.0 copyleft license (github.com/bunkerity/bunkerweb, verified 2026-11-02). You can self-host it on any VPS or homelab server at no license cost; the vendor also offers a paid PRO tier and a managed Cloud product with extra features, which the independent whiteravens overview distinguishes from the open-source core.
Does BunkerWeb replace Nginx?
No. BunkerWeb is built on the NGINX web server — it adds the WAF, reverse-proxy configuration, the Web UI, and the settings layer around it. Think of it as a security-hardened NGINX distribution that sits in front of your applications, not as a competitor to the Nginx beginner guides you may have read.
Do I need to install ModSecurity separately?
No. ModSecurity with the OWASP Core Rule Set is integrated and enabled by default in BunkerWeb (USE_MODSECURITY=yes, USE_MODSECURITY_CRS=yes). "BunkerWeb vs ModSecurity" is not a real choice — one ships inside the other.
Can I run BunkerWeb on a cheap VPS?
Yes — that is its natural home. One container, one shared Docker network for your apps, a persistent volume, and ports 80/443 open. Our VPS hosting primer covers the hosting shape. Just make sure DNS points at the server before enabling AUTO_LETS_ENCRYPT=yes, and use the staging flag while you test.
Do I need the Web UI to use BunkerWeb?
No — everything is configurable through environment variables, and docker logs shows the request stream. The Web UI (port 7000) is a convenience layer: dashboards, blocked-attack views, ban management, and settings editing without touching compose files.
