Skip to content
Klutch.sh Docs

Deploying SWAG

Introduction

SWAG (Secure Web Application Gateway) is an all-in-one reverse proxy solution from LinuxServer.io that combines Nginx, Let’s Encrypt, and fail2ban into a single, easy-to-configure container. It provides automatic SSL certificate management, reverse proxy configurations, and intrusion prevention for your web applications.

SWAG simplifies the complexity of securing and routing traffic to multiple services. Instead of managing separate containers for Nginx, Certbot, and fail2ban, SWAG bundles everything together with sensible defaults and extensive documentation.

Key highlights of SWAG:

  • Automatic SSL: Let’s Encrypt certificate generation and renewal
  • Reverse Proxy: Built-in Nginx with pre-made proxy configurations
  • Security: Integrated fail2ban for intrusion prevention
  • Wildcard Certificates: Support for wildcard SSL via DNS validation
  • Subdomain Management: Easy configuration for multiple subdomains
  • HTTP/2 and HTTP/3: Modern protocol support out of the box
  • ModSecurity: Optional web application firewall
  • GeoIP Blocking: Block traffic by geographic location
  • Authelia Integration: Single sign-on support
  • Pre-made Configs: Templates for popular applications
  • Docker Optimized: Designed for containerized environments

This guide walks through deploying SWAG on Klutch.sh using Docker, configuring reverse proxy rules, and securing your web applications.

Why Deploy SWAG on Klutch.sh

Deploying SWAG on Klutch.sh provides several advantages for web infrastructure:

Simplified Deployment: Klutch.sh handles the container orchestration while SWAG handles SSL and routing.

Persistent Storage: Attach volumes for certificates and configuration. Your SSL certs survive restarts.

Central Routing: Route traffic to multiple applications through a single entry point.

GitHub Integration: Store configurations in version control for reproducible deployments.

Security Stack: Get Nginx, Let’s Encrypt, and fail2ban working together out of the box.

Prerequisites

Before deploying SWAG on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your SWAG configuration
  • Basic familiarity with Docker and Nginx concepts
  • A domain name with DNS control (for SSL certificates)
  • (Optional) DNS API credentials for wildcard certificates

Deploying SWAG on Klutch.sh

    Create Your Repository

    Create a new GitHub repository for your SWAG deployment. Add a Dockerfile:

    FROM lscr.io/linuxserver/swag:latest
    

    ENV PUID=1000
    ENV PGID=1000
    ENV TZ=America/New_York
    ENV URL=yourdomain.com
    ENV VALIDATION=http
    ENV SUBDOMAINS=www,app,api
    ENV ONLY_SUBDOMAINS=false
    ENV STAGING=false
    

    EXPOSE 443 80
    

    HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
      CMD curl -fsk https://localhost/ || exit 1

    Push to GitHub

    Commit and push your Dockerfile to your GitHub repository.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 443 (SWAG handles SSL internally)

    Set Environment Variables

    Configure your domain and validation:

    VariableValue
    URLYour domain name
    VALIDATIONhttp or dns
    SUBDOMAINSComma-separated subdomains
    DNSPLUGINYour DNS provider (if using DNS validation)
    TZYour timezone

    Attach Persistent Volumes

    Add volumes for configuration and certificates:

    Mount PathRecommended SizePurpose
    /config5 GBAll SWAG configuration and certs

    Deploy Your Application

    Click Deploy to start the build process.

    Verify SSL Certificate

    Once deployed, SWAG will automatically obtain SSL certificates for your domain.

Configuration Structure

Directory Layout

SWAG organizes configuration in /config:

/config/
├── nginx/
│   ├── nginx.conf
│   ├── site-confs/
│   │   └── default.conf
│   └── proxy-confs/
│       ├── app.subdomain.conf.sample
│       └── app.subfolder.conf.sample
├── fail2ban/
│   └── jail.local
├── keys/
│   └── letsencrypt/
└── www/
    └── index.html

Nginx Configuration

Main configuration in nginx/site-confs/default.conf:

server {
    listen 443 ssl http2;
    server_name yourdomain.com;


    include /config/nginx/ssl.conf;


    location / {
        include /config/nginx/proxy.conf;
        proxy_pass http://your-app:8080;
    }
}

Reverse Proxy Setup

Subdomain Proxying

Create /config/nginx/proxy-confs/app.subdomain.conf:

server {
    listen 443 ssl http2;
    server_name app.yourdomain.com;


    include /config/nginx/ssl.conf;


    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app app-service;
        set $upstream_port 8080;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}

Subfolder Proxying

Create /config/nginx/proxy-confs/app.subfolder.conf:

location /app {
    include /config/nginx/proxy.conf;
    include /config/nginx/resolver.conf;
    set $upstream_app app-service;
    set $upstream_port 8080;
    set $upstream_proto http;
    proxy_pass $upstream_proto://$upstream_app:$upstream_port;
}

Pre-made Configurations

SWAG includes templates for popular apps:

Terminal window
# Copy and enable a template
cp /config/nginx/proxy-confs/nextcloud.subdomain.conf.sample \
   /config/nginx/proxy-confs/nextcloud.subdomain.conf

Available templates include:

  • Nextcloud, Plex, Jellyfin
  • Sonarr, Radarr, Lidarr
  • Home Assistant, Node-RED
  • Grafana, Portainer
  • And many more

SSL Certificate Configuration

HTTP Validation

Standard HTTP-01 challenge:

VALIDATION=http

Requires port 80 accessible from the internet.

DNS Validation

For wildcard certificates:

VALIDATION=dns
DNSPLUGIN=cloudflare

Create /config/dns-conf/cloudflare.ini:

dns_cloudflare_api_token = YOUR_API_TOKEN

Supported DNS Providers

  • Cloudflare
  • AWS Route53
  • DigitalOcean
  • Google Cloud DNS
  • Azure DNS
  • And many more

Security Configuration

Fail2ban Setup

Configure intrusion prevention in /config/fail2ban/jail.local:

[DEFAULT]
bantime = 600
findtime = 600
maxretry = 3


[nginx-http-auth]
enabled = true


[nginx-botsearch]
enabled = true

GeoIP Blocking

Block by country in Nginx:

# Include GeoIP database
geoip2 /config/geoip2db/GeoLite2-Country.mmdb {
    $geoip2_data_country_code country iso_code;
}


# Block specific countries
map $geoip2_data_country_code $allowed_country {
    default yes;
    CN no;
    RU no;
}

Rate Limiting

Implement rate limits:

limit_req_zone $binary_remote_addr zone=one:10m rate=10r/s;


server {
    location / {
        limit_req zone=one burst=20 nodelay;
    }
}

Authentication

Basic Authentication

Add HTTP basic auth:

location /admin {
    auth_basic "Restricted";
    auth_basic_user_file /config/nginx/.htpasswd;
    proxy_pass http://admin-app:8080;
}

Create password file:

Terminal window
htpasswd -c /config/nginx/.htpasswd username

Authelia Integration

Enable single sign-on:

include /config/nginx/authelia-server.conf;


location / {
    include /config/nginx/authelia-location.conf;
    proxy_pass http://your-app:8080;
}

ModSecurity WAF

Enabling ModSecurity

Uncomment in nginx.conf:

modsecurity on;
modsecurity_rules_file /config/nginx/modsecurity.conf;

Custom Rules

Add rules in /config/nginx/modsecurity.conf:

SecRule ARGS "@contains <script>" "id:1,deny,status:403"

Best Practices

Security Hardening

  • Enable HTTP Strict Transport Security (HSTS)
  • Configure Content Security Policy
  • Use strong SSL parameters
  • Implement rate limiting
  • Enable fail2ban jails

Performance

  • Enable gzip compression
  • Configure caching headers
  • Use HTTP/2 (enabled by default)
  • Consider HTTP/3 for modern clients

Maintenance

  • Monitor certificate expiration
  • Review fail2ban logs
  • Update container regularly
  • Backup configuration

Troubleshooting

Certificate Issues

  • Verify DNS points to server
  • Check port 80/443 accessibility
  • Review Let’s Encrypt logs
  • Try staging mode first

Proxy Not Working

  • Verify upstream service is running
  • Check network connectivity
  • Review Nginx error logs
  • Test with curl from container

Fail2ban Blocking

  • Check fail2ban logs
  • Unban IP if needed: fail2ban-client set jail unbanip IP
  • Review jail configuration

Additional Resources

Conclusion

Deploying SWAG on Klutch.sh provides a comprehensive reverse proxy solution with automatic SSL, security features, and easy configuration. The all-in-one approach simplifies web infrastructure management while providing enterprise-grade features. Combined with Klutch.sh’s reliable hosting, you get a secure, maintainable gateway for all your web applications.