A zero-privilege perimeter reverse proxy and TLS gateway based on Angie. It serves as an isolated edge entry point for multi-tenant containerized workloads—such as wordpress-docker and speedybench—communicating over a dedicated internal Docker network (frontend_gateway).
Most Docker Compose guides and deployment setups for Angie prioritize rapid initial setup over operational security. In practice, this promotes patterns that compromise host isolation and leave the edge under-configured:
- Host Port Exposure: Workloads are routinely configured to publish ports directly to the host network—even when bound to
127.0.0.1—breaking container network isolation, risking port collisions, and exposing internal application tiers to the host network stack. - Insecure Container Runtimes: Typical setups execute edge proxies as root, retain all Linux capabilities, keep container filesystems fully writable, and run without CPU or memory limits, significantly amplifying the blast radius of any web exploit.
- Inadequate Default Configurations: Stock Angie container images provide only bare-minimum configuration stubs, lacking critical perimeter protections such as trusted Cloudflare real client IP validation, security response headers, and RFC 8470 0-RTT anti-replay mitigation.
- Perimeter Fingerprinting & Information Leakage: Default error handling regularly exposes backend server signatures, PHP versions, and raw upstream error traces during outages, simplifying automated reconnaissance.
- Closed-Circuit Multi-Tenant Network: Provisions and manages the isolated
frontend_gatewaynetwork on subnet172.20.0.0/16with a dedicated static IP (172.20.0.254) for the Edge gateway. Internal tenant containers such as${SITE_USER}_angiefromwordpress-dockerandspeedybenchattach to this network with zero exposed host ports and strictly authorize traffic originating from172.20.0.254. - Zero-Privilege Security Profile: Operates under a dedicated unprivileged non-root user with an immutable read-only filesystem, strips all Linux kernel capabilities except binding privileged network ports, prevents privilege escalation, and enforces strict CPU and memory resource limits.
- Decoupled Hardened Configuration Suite: Replaces minimal stock container stubs with fully externalized, read-only host configurations—including extended MIME type mappings, dynamic module declarations, and modular protocol snippets—guaranteeing deterministic edge behavior and total control over runtime settings.
- Native In-Process ACME: Built-in Let's Encrypt certificate issuance and automated renewal directly within Angie using
acme_client, eliminating separate certbot containers, cron jobs, and external ACME socket mounts. - HTTP/3 & Modern Transport Security: Native HTTP/3 over QUIC/UDP 443 and HTTP/2, TLS 1.3/1.2 with custom Diffie-Hellman parameters, MTU-tuned 1369-byte TLS record sizing, session resumption, and RFC 8470 compliant 0-RTT anti-replay attack mitigation, among other transport hardening controls.
- Automated Cloudflare Real IP Synchronization: Dedicated host script and cron job fetch official Cloudflare IPv4/IPv6 CIDRs, configure trusted proxy ranges for real client IP restoration via the
CF-Connecting-IPheader, perform container syntax validation, and trigger graceful reloads under an exclusive lock. - Perimeter Hardening & Zero Information Leakage: Universal baseline security headers with per-domain CSP customization, and anonymous perimeter error pages that eliminate reconnaissance by preventing leakage of server signatures, PHP versions, or OS details.
- Dynamic Compression & Module Extensibility: Brotli and Zstandard dynamic compression modules are enabled by default alongside standard Gzip, with the ability to activate any additional pre-compiled dynamic module from the official Angie image via
modules.conf. - Zero-Downtime Host Log Rotation: Systemd-driven host logrotate configuration rotates container logs daily with gzip compression and signals Angie via
USR1to reopen descriptors without dropping active connections.
Production Directory Structure
/
├── etc/
│ ├── cron.d/
│ │ └── update-cf-ips # Weekly Cloudflare IP updater cron job
│ └── logrotate.d/
│ └── angie # Angie logrotate configuration
├── usr/local/bin/
│ ├── angie # Angie container CLI wrapper script
│ └── update-cf-ips.sh # Cloudflare IP fetch and reload script
└── home/angie/ # Dedicated non-root user home directory
├── docker-compose.yaml # Production stack deployment manifest
├── .env # Host environment variables file
└── data/ # Persistent Angie runtime data and configuration
├── angie.conf # Main Angie server configuration
├── mime.types # Extended MIME type mappings
├── modules.conf # Dynamic modules configuration
├── certs/ # ACME Let's Encrypt certificates
├── cache/ # Proxy cache storage
├── html/ # Static HTML files
├── ssl/ # SSL configuration directory
│ └── dhparam.pem # Generated Diffie-Hellman parameters
├── logs/ # Angie system error logs
│ └── domains/ # Per-domain access and error logs
└── conf.d/ # Configuration snippets and virtual hosts
├── 0rtt-anti-replay.conf # TLS 1.3 0-RTT replay attack mitigation
├── cloudflare-ips.inc # Trusted Cloudflare IP ranges generated via script
├── error-pages.inc # Perimeter error pages
├── healthcheck.inc # Container healthcheck endpoint
├── http-protocols.conf # HTTP/2 and HTTP/3 activation directives
├── security-headers.inc # Security response headers
└── domains/ # Per-domain virtual host configurations
└── <site_user>.conf # Deployed virtual host configuration
Deployment & Setup
- Docker Engine & Compose: Ensure Docker Engine and Docker Compose plugin are installed on the host. Follow the official installation guide for Ubuntu.
- Network Ports: The host must have ports
80/tcp,443/tcp, and443/udp(for HTTP/3 QUIC) open and not occupied by other services.
Choose a dedicated, unprivileged numeric ID unique to this service on your host and verify that it is not in use:
APP_UID=<CHOSEN_UID>
getent passwd ${APP_UID}
getent group ${APP_UID}If neither command produces output, create the system group and user with a disabled login shell, and configure base directory ownership:
Create an unprivileged system account with a matching user-group (-U) and disabled login shell:
sudo useradd -M -d /home/angie -s /usr/sbin/nologin -u ${APP_UID} -U angieCreate the base directory and assign ownership:
sudo mkdir -p /home/angie
sudo chown root:angie /home/angie
sudo chmod 0750 /home/angiesudo mkdir -p /home/angie/data/{cache,certs,conf.d/{domains,main},html,logs/domains,ssl}
sudo chown -R root:angie /home/angie/data/{conf.d,html,ssl}
sudo find /home/angie/data/{conf.d,html,ssl} -type d -exec chmod 0750 {} +
sudo chown -R angie:angie /home/angie/data/{cache,certs,logs}
sudo find /home/angie/data/{cache,certs,logs} -type d -exec chmod 0700 {} +Generate custom 2048-bit Diffie-Hellman parameters and set strict owner-only permissions:
sudo openssl dhparam -out /home/angie/data/ssl/dhparam.pem 2048
sudo chown root:angie /home/angie/data/ssl/dhparam.pem
sudo chmod 0440 /home/angie/data/ssl/dhparam.pemDownload the complete set of configuration files and conf.d snippets from the repository:
REPO="https://raw.githubusercontent.com/webstudiobond/angie-docker-compose/main"
sudo curl -fsSL ${REPO}/data/angie.conf -o /home/angie/data/angie.conf
sudo curl -fsSL ${REPO}/data/mime.types -o /home/angie/data/mime.types
sudo curl -fsSL ${REPO}/data/modules.conf -o /home/angie/data/modules.conf
sudo curl -fsSL ${REPO}/data/conf.d/0rtt-anti-replay.conf -o /home/angie/data/conf.d/0rtt-anti-replay.conf
sudo curl -fsSL ${REPO}/data/conf.d/error-pages.inc -o /home/angie/data/conf.d/error-pages.inc
sudo curl -fsSL ${REPO}/data/conf.d/healthcheck.inc -o /home/angie/data/conf.d/healthcheck.inc
sudo curl -fsSL ${REPO}/data/conf.d/http-protocols.conf -o /home/angie/data/conf.d/http-protocols.conf
sudo curl -fsSL ${REPO}/data/conf.d/security-headers.inc -o /home/angie/data/conf.d/security-headers.incsudo curl -fsSL ${REPO}/docker-compose.yaml -o /home/angie/docker-compose.yaml
sudo curl -fsSL ${REPO}/.env.example -o /home/angie/.env
sudo chown root:root /home/angie/{docker-compose.yaml,.env}
sudo chmod 0600 /home/angie/{docker-compose.yaml,.env}sed -i "s/^APP_UID=.*/APP_UID=${APP_UID}/" /home/angie/.env
sed -i "s/^APP_GID=.*/APP_GID=${APP_UID}/" /home/angie/.envOpen /home/angie/.env, set HOST_IP to your server's public IPv4 address (defaults to 127.0.0.1 for safe local binding):
sudo nano /home/angie/.envAutomate periodic fetching of the latest official Cloudflare IPv4 and IPv6 CIDR ranges to ensure CF-Connecting-IP restoration remains accurate.
Download the update script and install it with execution permissions:
REPO="https://raw.githubusercontent.com/webstudiobond/angie-docker-compose/main"
sudo curl -fsSL ${REPO}/usr/local/bin/update-cf-ips.sh -o /usr/local/bin/update-cf-ips.sh
sudo chown root:root /usr/local/bin/update-cf-ips.sh
sudo chmod 0500 /usr/local/bin/update-cf-ips.shExecute the script to verify IP download, syntax checking, and Angie container reloading:
sudo /usr/local/bin/update-cf-ips.shInstall and activate the weekly automated cron job:
sudo curl -fsSL ${REPO}/etc/cron.d/update-cf-ips -o /etc/cron.d/update-cf-ips
sudo chown root:root /etc/cron.d/update-cf-ips
sudo chmod 0400 /etc/cron.d/update-cf-ipsKeep deployment inputs, server configurations, and system scripts outside the service account's write access. The container runs with numeric APP_UID:APP_GID (angie:angie, typically 2001:2001) and requires write access strictly to runtime storage directories (cache/, certs/, and logs/). Under this model, a compromised Angie edge process cannot modify server configurations, overwrite virtual hosts, or manipulate Docker manifests.
All server configurations and snippets are owned by root:angie with read-only permissions (0440 for configuration files, snippets, and domain virtual hosts, 0640 for the dynamically generated Cloudflare IP list, 0750 for directories). Runtime caches and ACME TLS certificate keys are isolated to angie:angie with owner-only access (0700 for directories, 0600 for files).
Runtime log storage (logs/, logs/domains/) is owned by angie:angie with 0750 for directories and 0640 for files. Host security and intrusion detection systems (such as CrowdSec) and log rotation daemons operate with root or service privileges, seamlessly reading logs without exposing them to other unprivileged host users.
| Host path | Owner | Mode | Reason |
|---|---|---|---|
/home/angie, /home/angie/data |
root:angie |
0750 |
Base directories; allows service traversal without access for other users |
docker-compose.yaml, .env |
root:root |
0600 |
Host-only manifests and environment settings |
data/angie.conf, mime.types, modules.conf |
root:angie |
0440 |
Read-only server configuration and dynamic module includes |
data/conf.d/ and subdirectories |
root:angie |
0750 |
Read-only configuration snippets and virtual hosts |
data/conf.d/* files (snippets) |
root:angie |
0440 |
Strictly read-only configuration directives and snippets |
data/conf.d/domains/*.conf |
root:angie |
0440 |
Strictly read-only domain virtual host configurations |
data/conf.d/cloudflare-ips.inc |
root:angie |
0640 |
Dynamically updated Cloudflare IP include file |
data/ssl/ directory |
root:angie |
0750 |
Read-only SSL configuration directory |
data/ssl/dhparam.pem |
root:angie |
0440 |
Read-only Diffie-Hellman parameters |
data/html/ directory and files |
root:angie |
0750 / 0440 |
Read-only static maintenance and error assets |
data/certs/ and subdirectories |
angie:angie |
0700 |
Private ACME Let's Encrypt certificates and account keys |
data/certs/* files |
angie:angie |
0600 |
Private ACME certificates and private keys |
data/cache/ and subdirectories |
angie:angie |
0700 |
Private proxy cache storage |
data/cache/* files |
angie:angie |
0600 |
Private proxy cache storage files |
data/logs/, data/logs/domains/ |
angie:angie |
0750 |
Writable log storage and per-domain log directory |
data/logs/*.log, data/logs/domains/*.log |
angie:angie |
0640 |
Server and virtual host access/error logs |
/usr/local/bin/angie (optional) |
root:root |
0500 |
Optional host CLI wrapper script (Method 1) |
/usr/local/bin/update-cf-ips.sh |
root:root |
0500 |
Cloudflare IP fetch and container reload script |
/etc/cron.d/update-cf-ips |
root:root |
0400 |
System cron configuration for weekly IP updater |
/etc/logrotate.d/angie |
root:root |
0400 |
System logrotate configuration |
Run as a host administrator after creating files and after any configuration or snippet update:
sudo chown root:angie /home/angie /home/angie/data
sudo chmod 0750 /home/angie /home/angie/data
sudo chown root:root /home/angie/docker-compose.yaml /home/angie/.env
sudo chmod 0600 /home/angie/docker-compose.yaml /home/angie/.env
sudo chown root:angie /home/angie/data/{angie.conf,mime.types,modules.conf}
sudo chmod 0440 /home/angie/data/{angie.conf,mime.types,modules.conf}
sudo chown -R root:angie /home/angie/data/{conf.d,html,ssl}
sudo find /home/angie/data/{conf.d,html,ssl} -type d -exec chmod 0750 {} +
sudo find /home/angie/data/{conf.d,html} -type f -exec chmod 0440 {} +
[ -f /home/angie/data/conf.d/cloudflare-ips.inc ] && sudo chmod 0640 /home/angie/data/conf.d/cloudflare-ips.inc
[ -f /home/angie/data/ssl/dhparam.pem ] && sudo chmod 0440 /home/angie/data/ssl/dhparam.pem
sudo chown -R angie:angie /home/angie/data/{cache,certs,logs}
sudo find /home/angie/data/{cache,certs,logs} -type d -exec chmod 0700 {} +
sudo find /home/angie/data/{cache,certs,logs} -type f -exec chmod 0600 {} +
[ -f /usr/local/bin/angie ] && sudo chown root:root /usr/local/bin/angie && sudo chmod 0500 /usr/local/bin/angie
[ -f /usr/local/bin/update-cf-ips.sh ] && sudo chown root:root /usr/local/bin/update-cf-ips.sh && sudo chmod 0500 /usr/local/bin/update-cf-ips.sh
[ -f /etc/cron.d/update-cf-ips ] && sudo chown root:root /etc/cron.d/update-cf-ips && sudo chmod 0400 /etc/cron.d/update-cf-ips
[ -f /etc/logrotate.d/angie ] && sudo chown root:root /etc/logrotate.d/angie && sudo chmod 0400 /etc/logrotate.d/angiePull images and start the container:
sudo docker compose -f /home/angie/docker-compose.yaml pull
sudo docker compose -f /home/angie/docker-compose.yaml up -dTo view real-time container logs:
sudo docker compose -f /home/angie/docker-compose.yaml logs -f angieTo stop the container:
sudo docker compose -f /home/angie/docker-compose.yaml stopTo stop and remove container and networks:
sudo docker compose -f /home/angie/docker-compose.yaml downLog Rotation & Systemd Timer
Install logrotate on the host:
sudo apt update && sudo apt install -y logrotateDownload the Angie logrotate configuration:
REPO="https://raw.githubusercontent.com/webstudiobond/angie-docker-compose/main"
sudo curl -fsSL ${REPO}/etc/logrotate.d/angie -o /etc/logrotate.d/angie
sudo chown root:root /etc/logrotate.d/angie
sudo chmod 0400 /etc/logrotate.d/angieVerify the logrotate configuration syntax in debug mode:
sudo logrotate -d /etc/logrotate.d/angieAdjust the systemd logrotate timer to execute daily at 03:00:
sudo systemctl edit logrotate.timer[Timer]
OnCalendar=
OnCalendar=*-*-* 03:00:00Reload systemd daemon and restart the timer:
sudo systemctl daemon-reload
sudo systemctl restart logrotate.timerEdge Proxy Administration & CLI Helper
Install the Angie container CLI wrapper script to /usr/local/bin/angie and set execution permissions:
REPO="https://raw.githubusercontent.com/webstudiobond/angie-docker-compose/main"
sudo curl -fsSL ${REPO}/usr/local/bin/angie -o /usr/local/bin/angie
sudo chown root:root /usr/local/bin/angie
sudo chmod 0500 /usr/local/bin/angieTest configuration syntax and reload Angie gracefully without dropping connections:
sudo angie -t && sudo angie -s reloadUseful management commands using the system wrapper:
sudo angie -V
sudo ls -la /home/angie/data/certs/
sudo tail -f /home/angie/data/logs/domains/wordpress.logWhen operating directly as root, define a shell function in ~/.bashrc:
nano ~/.bashrcangie() {
docker exec angie angie "$@"
}Apply the changes to your current session:
source ~/.bashrcTest configuration syntax and reload Angie gracefully without dropping connections:
angie -t && angie -s reloadUseful management commands when operating as root:
angie -V
ls -la /home/angie/data/certs/
tail -f /home/angie/data/logs/domains/wordpress.logVirtual Host Setup
Virtual host configurations are created on demand as needed when deploying sites or services. Pre-configured templates are available in data/conf.d/domains/, each containing a self-documenting header with all required placeholders.
The guide below demonstrates deploying a WordPress virtual host as an example.
WordPress Integration (wordpress-docker)
Download the WordPress virtual host template directly to your site configuration file:
REPO="https://raw.githubusercontent.com/webstudiobond/angie-docker-compose/main"
SITE_USER="mywpsite"
sudo curl -fsSL ${REPO}/data/conf.d/domains/wordpress.conf \
-o /home/angie/data/conf.d/domains/${SITE_USER}.conf
sudo chown root:angie /home/angie/data/conf.d/domains/${SITE_USER}.conf
sudo chmod 0440 /home/angie/data/conf.d/domains/${SITE_USER}.confSubstitute the placeholders inside the configuration file so upstream requests route to ${SITE_USER}_angie:80 on the frontend_gateway network:
DOMAIN="example.com"
sudo sed -i \
-e "s|wordpress\.example|${DOMAIN}|g" \
-e "s|mysite|${SITE_USER}|g" \
/home/angie/data/conf.d/domains/${SITE_USER}.confReview and customize the configuration as needed (e.g., adjust server_name or conditional access logging rules):
sudo nano /home/angie/data/conf.d/domains/${SITE_USER}.conf- Test Angie configuration syntax:
sudo angie -t-
Point your domain's public DNS A/AAAA records to the server IP.
-
Once DNS propagates, reload Angie to apply changes and issue the TLS certificate:
sudo angie -s reload- Verify live HTTPS response and TLS handshake:
curl -I https://example.comAuthelia SSO Integration (Optional)
When securing internal application routes (such as administrative panels or private subdirectories) using authelia-docker, download the Authelia configuration snippets and activate forward authentication within your virtual host.
This configuration is designed specifically to serve Authelia under a subpath (default /authelia) on the same domain without requiring a dedicated subdomain.
To customize the subpath (for example, to /sso):
- Authelia (
configuration.yml):server: address: 'tcp://:9091/sso'
- Angie (
/etc/angie/conf.d/authelia-public-ui.inc): Update the location path and upstream target:location ^~ /sso { proxy_pass http://authelia_backend/sso; ...
Download the upstream configuration and auth-request helper snippets from the repository:
REPO="https://raw.githubusercontent.com/webstudiobond/angie-docker-compose/main"
sudo curl -fsSL ${REPO}/data/conf.d/authelia-upstream.conf -o /home/angie/data/conf.d/authelia-upstream.conf
sudo curl -fsSL ${REPO}/data/conf.d/authelia-internal-verify.inc -o /home/angie/data/conf.d/authelia-internal-verify.inc
sudo curl -fsSL ${REPO}/data/conf.d/authelia-internal-verify-basic-auth.inc -o /home/angie/data/conf.d/authelia-internal-verify-basic-auth.inc
sudo curl -fsSL ${REPO}/data/conf.d/authelia-public-ui.inc -o /home/angie/data/conf.d/authelia-public-ui.inc
sudo curl -fsSL ${REPO}/data/conf.d/authelia-protect.inc -o /home/angie/data/conf.d/authelia-protect.inc
sudo curl -fsSL ${REPO}/data/conf.d/authelia-user-claims.inc -o /home/angie/data/conf.d/authelia-user-claims.inc
sudo chown root:angie /home/angie/data/conf.d/authelia-upstream.conf \
/home/angie/data/conf.d/authelia-internal-verify.inc \
/home/angie/data/conf.d/authelia-internal-verify-basic-auth.inc \
/home/angie/data/conf.d/authelia-public-ui.inc \
/home/angie/data/conf.d/authelia-protect.inc \
/home/angie/data/conf.d/authelia-user-claims.inc
sudo chmod 0440 /home/angie/data/conf.d/authelia-upstream.conf \
/home/angie/data/conf.d/authelia-internal-verify.inc \
/home/angie/data/conf.d/authelia-internal-verify-basic-auth.inc \
/home/angie/data/conf.d/authelia-public-ui.inc \
/home/angie/data/conf.d/authelia-protect.inc \
/home/angie/data/conf.d/authelia-user-claims.incIn your domain virtual host configuration (for example, /home/angie/data/conf.d/domains/couchdb.conf), choose the verification snippet matching your authentication model:
- Cookie-Only Verification (
authelia-internal-verify.inc): Default for web applications and services managing their own internal Basic Auth, bearer tokens, or API keys. Clears theAuthorizationheader prior to querying Authelia, verifying requests solely via browser session cookies and preventing collisions with backend passwords. - Basic Auth Forwarding (
authelia-internal-verify-basic-auth.inc): For services accessed by native mobile applications or API clients that authenticate directly against Authelia using HTTP Basic Auth credentials. Forwards incoming credentials to Authelia'sHeaderAuthorizationstrategy.
Inside the server block (Option A — Cookie-only verification):
include /etc/angie/conf.d/authelia-internal-verify.inc;
include /etc/angie/conf.d/authelia-public-ui.inc;Inside the server block (Option B — Basic Auth forwarding verification):
include /etc/angie/conf.d/authelia-internal-verify-basic-auth.inc;
include /etc/angie/conf.d/authelia-public-ui.inc;Inside any location block requiring perimeter protection (e.g., administrative interfaces):
include /etc/angie/conf.d/authelia-protect.inc;Optionally, if the backend service supports ForwardAuth / HTTP header authentication (such as CouchDB proxy auth):
include /etc/angie/conf.d/authelia-user-claims.inc;Important:
authelia-user-claims.incmust only be included inside alocationblock alongsideauthelia-protect.inc(never at theserverlevel). Because Nginx/Angie disables parentproxy_set_headerinheritance when any header directive is declared in a location, if your virtual host defines base proxy headers (Host,X-Real-IP,X-Forwarded-*) at theserverlevel, you must move or declare those base proxy headers directly inside the targetlocationblock.
angie -t && angie -s reloadDevelopment & Testing
For local development and testing guidelines, refer to DEVELOPMENT.
License & Attribution
This repository and deployment architecture are licensed under the MIT License. This project is an independent containerized deployment architecture and is not affiliated with, endorsed, or sponsored by Angie.
Angie License & Attribution: All rights to Angie belong to its respective authors and copyright holders. For terms of distribution and use, refer to the official Angie License.