Reverse proxy
For production deployments, place Bulwark behind a reverse proxy for TLS termination and custom domains.
Caddy
The simplest option, with automatic HTTPS from Let's Encrypt:
mail.example.com {
reverse_proxy bulwark:3000
}
Nginx
server {
listen 443 ssl;
http2 on; # nginx 1.25.1+; older versions: listen 443 ssl http2;
server_name mail.example.com;
ssl_certificate /etc/ssl/cert.pem;
ssl_certificate_key /etc/ssl/key.pem;
client_max_body_size 100m;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
}
}
Plugin uploads to Nextcloud and saves from ONLYOFFICE or Collabora send up to 100 MB per request through Bulwark. nginx refuses bodies over 1 MB by default, hence client_max_body_size.
Traefik
Using Docker labels:
bulwark:
image: ghcr.io/bulwarkmail/webmail:latest
labels:
- "traefik.enable=true"
- "traefik.http.routers.bulwark.rule=Host(`mail.example.com`)"
- "traefik.http.routers.bulwark.tls.certresolver=letsencrypt"
- "traefik.http.services.bulwark.loadbalancer.server.port=3000"
Proxy requirements
Required headers
Whatever reverse proxy you use, make sure to forward these headers:
X-Forwarded-For- Client IP addressX-Forwarded-Proto- Original protocol (http/https)Host- Original hostname
EventSource support
Push notifications ride on a JMAP EventSource that the browser opens to Stalwart directly, not through the proxy in front of Bulwark. If Stalwart sits behind nginx, that proxy must keep long connections open and not buffer them: add proxy_buffering off; and a long proxy_read_timeout to its JMAP location.
Session URL rewriting
Bulwark moves the JMAP session URLs the server returns onto the origin of the configured server URL. Without this, a Stalwart that advertises an internal hostname such as http://stalwart:8080 would hand the browser an address it cannot reach. URLs the server deliberately serves from another HTTPS host are left alone.
Subpath deployment
To mount Bulwark under a URL prefix (e.g. https://example.com/webmail):
- Build a custom image with the path and the locale prefix mode baked in. Next.js reads both at build time, so setting them on a running container does nothing.
NEXT_PUBLIC_LOCALE_PREFIX=alwaysavoidsnext-intlrewrite loops under a subpath:
The publisheddocker build --build-arg NEXT_PUBLIC_BASE_PATH=/webmail --build-arg NEXT_PUBLIC_LOCALE_PREFIX=always -t bulwark-webmail .-alwaysimages (for exampleghcr.io/bulwarkmail/webmail:1.19.1-always) are built with the locale prefix mode but without a base path, so they don't replace this build for a subpath. - Point your reverse proxy at the container without stripping the prefix. The app expects to receive requests under
/webmail/...and serves all routes (/webmail/api/...,/webmail/_next/static/...,/webmail/sw.js, etc.) accordingly.
example.com {
reverse_proxy /webmail/* bulwark:3000
}
location /webmail/ {
proxy_pass http://localhost:3000/webmail/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
PWA paths
If Bulwark serves a PWA, make sure these paths are forwarded as-is and not aggressively cached at the proxy:
/manifest.webmanifest- dynamic manifest/sw.js- service worker (scope is automatically adjusted under a subpath)/api/pwa-icon/*- auto-generated PWA icons/branding/*- branding assets/api/push/preview- fetches the text of a push notification for the service worker
Next step
With Bulwark on HTTPS, users can install it as a Progressive Web App and get web push. To keep it current, see Updating.