SWAG (Secure Web Application Gateway)

SWAG (Secure Web Application Gateway) is a self‑hosted reverse‑proxy and SSL/TLS terminator built on Nginx with integrated Let’s Encrypt automation. It is packaged as a Docker image by LinuxServer.io, enabling rapid deployment across diverse environments—from home labs to production clusters. At its core, SWAG exposes a single entry point that forwards requests to internal services while handling HTTPS termination, HSTS headers, HTTP/2, and optional authentication layers such as Basic Auth or OAuth. The container exposes a minimal configuration directory (/config) that persists across restarts, allowing developers to define virtual hosts through declarative conf.d files and control SSL settings via environment variables.

Key Features

• Automated HTTPS: Automatic issuance and renewal of Let’s Encrypt certificates, with support for multiple domains and SANs.
• Reverse‑Proxy Flexibility: Configurable upstream servers, load balancing policies (round‑robin, least_conn), health checks, and sticky sessions.
• Security Hardening: Built‑in HSTS, CSP headers, secure cookie flags, and optional rate limiting or IP whitelisting.
• Authentication Hooks: Basic Auth, LDAP, OAuth2 providers (Google, GitHub), and custom Lua scripts for advanced auth logic.
• Logging & Metrics: Structured access logs, error logs, and optional integration with Prometheus via the nginx-prometheus-exporter.

Technical Stack

• Nginx 1.25+ (high‑performance event‑driven web server) as the core reverse proxy.
• OpenSSL for TLS cryptography; supports TLS 1.3 and modern cipher suites.
• Let's Encrypt Certbot (Python) for automated certificate management.
• s6 Overlay as the init system inside the container, ensuring graceful process supervision and PID 1 handling.
• Alpine Linux base image (minimal footprint, musl libc) to reduce attack surface and image size.

Core Capabilities

• Virtual Host Configuration: Each host is defined in /config/nginx/virtual-hosts.d/*.conf, allowing per‑domain routing rules, SSL options, and custom headers.
• API Endpoints: SWAG exposes a lightweight HTTP API (via nginx status modules) that can be polled for health checks, and a Certbot webhook endpoint (/certbot-webhook) that can trigger custom actions post‑renewal.
• Extensibility: Lua scripts (/config/nginx/lua.d) can be injected into the request lifecycle, enabling dynamic routing or custom authentication flows without rebuilding the image.
• Webhooks: Integration points for CI/CD pipelines to trigger SSL renewals or reload Nginx without downtime.

Deployment & Infrastructure

• Containerization: The image is fully Docker‑ready, with exposed ports 80 and 443. It can run on Docker Compose, Kubernetes (via Helm charts or raw manifests), or any OCI‑compatible runtime.
• Scalability: Multiple instances can be run behind a load balancer or DNS round‑robin, each sharing a shared NFS or Ceph volume for certificate storage (/config/certificates).
• Resource Footprint: Typically < 200 MiB RAM and minimal CPU overhead, making it suitable for edge devices or low‑cost VPS.
• Persistence: All configuration and certificates are stored in a bind mount, ensuring zero data loss across container restarts.

Integration & Extensibility

• Plugin System: While SWAG itself is a monolithic Nginx container, developers can layer additional services (e.g., an OAuth proxy like oauth2-proxy) as sidecar containers, sharing the same network namespace.
• Webhooks & Automation: Certbot’s --deploy-hook can trigger a container restart or notify a monitoring system. Conversely, the SWAG API can be called from external scripts to reload configuration after a change.
• Custom Scripts: The docker-entrypoint.sh supports user‑supplied shell scripts to run before Nginx starts, enabling dynamic configuration generation or environment variable injection.

Developer Experience

• Configuration Simplicity: The declarative conf.d format aligns with Nginx’s native syntax, reducing the learning curve. Environment variables expose common settings (e.g., PUID, PGID, LETSENCRYPT_EMAIL).
• Documentation Quality: The repository contains a detailed README, CONTRIBUTING guide, and links to community resources (Discord, Discourse). The docker-compose.yml example demonstrates typical usage patterns.
• Community Support: Active GitHub issues, Discord channels, and a dedicated forum provide quick assistance. The LinuxServer.io ecosystem ensures regular security patches and back‑porting of new Nginx features.

Use Cases

1. Home Lab Gateway: Expose multiple internal services (Nextcloud, Plex, Home Assistant) behind a single HTTPS front‑end with automated certs.
2. Microservice Edge Proxy: Deploy SWAG as a sidecar to a Kubernetes pod, providing TLS termination and traffic shaping without modifying application code.
3. API Gateway: Route external API calls to internal microservices, applying rate limits and OAuth2 authentication via Lua scripts.
4. Multi‑Tenant Hosting: Host several customer domains on the same server, each with isolated SSL certificates and custom security headers.

Advantages

• **