Portainer Templates logo

Portainer Templates

Swag Swag

Reverse Proxy

SWAG - Secure Web Application Gateway (formerly known as letsencrypt, no relation to Let's Encrypt™) sets up an Nginx webserver and reverse proxy with php support and a built-in certbot client that automates free SSL server certificate generation and renewal processes (Let's Encrypt and ZeroSSL). It also contains fail2ban for intrusion prevention.

Image details

Pulls: 90.8M
Architectures: amd64, arm64
Image size: 152 MB
Latest: 5.7.0
User: linuxserver
Created: Aug 03, 2020
Updated: 2 days ago
Status: active

Configuration

Type
Container
Platform
linux
Image
linuxserver/swag:latest
Ports
443:443/tcp80:80/tcp443:443/udp
Volumes
/config : /srv/lsio/swag/config
Env vars
PUID=1000PGID=1000TZ=Etc/UTCURL=example.comVALIDATION=httpSUBDOMAINS=www,CERTPROVIDER=CERT_PROFILE=DNSPLUGIN=cloudflarePROPAGATION=EMAIL=ONLY_SUBDOMAINS=falseEXTRA_DOMAINS=STAGING=falseDISABLE_F2B=SWAG_AUTORELOAD=SWAG_AUTORELOAD_WATCHLIST=
Restart
unless-stopped

Template by technorabilia

Notes

Portainer App Templates by Technorabilia, based on data provided by LinuxServer.io.

Ensure to create the following volume directories on the host file system, or modify the paths in the volume mapping section under the advanced options below, as needed.

mkdir -p /srv/lsio/swag/config

Installation

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select the app you wish to deploy, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo

docker run -d --name Swag \
  -p 443:443/tcp \
  -p 80:80/tcp \
  -p 443:443/udp \
  -e 'PUID=1000' \
  -e 'PGID=1000' \
  -e 'TZ=Etc/UTC' \
  -e 'URL=example.com' \
  -e 'VALIDATION=http' \
  -e 'SUBDOMAINS=www,' \
  -e 'CERTPROVIDER=' \
  -e 'CERT_PROFILE=' \
  -e 'DNSPLUGIN=cloudflare' \
  -e 'PROPAGATION=' \
  -e 'EMAIL=' \
  -e 'ONLY_SUBDOMAINS=false' \
  -e 'EXTRA_DOMAINS=' \
  -e 'STAGING=false' \
  -e 'DISABLE_F2B=' \
  -e 'SWAG_AUTORELOAD=' \
  -e 'SWAG_AUTORELOAD_WATCHLIST=' \
  -v /srv/lsio/swag/config:/config \
  --restart=unless-stopped \
  linuxserver/swag:latest

Save this file as compose.yaml and run docker compose up -d
Use this only as a guide.

services:
  swag:
    image: linuxserver/swag:latest
    ports:
      - 443:443/tcp
      - 80:80/tcp
      - 443:443/udp
    volumes:
      - /srv/lsio/swag/config:/config
    environment:
      PUID: '1000'
      PGID: '1000'
      TZ: Etc/UTC
      URL: example.com
      VALIDATION: http
      SUBDOMAINS: www,
      CERTPROVIDER: ''
      CERT_PROFILE: ''
      DNSPLUGIN: cloudflare
      PROPAGATION: ''
      EMAIL: ''
      ONLY_SUBDOMAINS: 'false'
      EXTRA_DOMAINS: ''
      STAGING: 'false'
      DISABLE_F2B: ''
      SWAG_AUTORELOAD: ''
      SWAG_AUTORELOAD_WATCHLIST: ''
    restart: unless-stopped

Save this file as swag-stack.yml, then from a manager node, run docker stack deploy -c swag-stack.yml swag

version: '3.8'
services:
  swag:
    image: linuxserver/swag:latest
    ports:
      - 443:443/tcp
      - 80:80/tcp
      - 443:443/udp
    volumes:
      - /srv/lsio/swag/config:/config
    environment:
      PUID: '1000'
      PGID: '1000'
      TZ: Etc/UTC
      URL: example.com
      VALIDATION: http
      SUBDOMAINS: www,
      CERTPROVIDER: ''
      CERT_PROFILE: ''
      DNSPLUGIN: cloudflare
      PROPAGATION: ''
      EMAIL: ''
      ONLY_SUBDOMAINS: 'false'
      EXTRA_DOMAINS: ''
      STAGING: 'false'
      DISABLE_F2B: ''
      SWAG_AUTORELOAD: ''
      SWAG_AUTORELOAD_WATCHLIST: ''
    deploy:
      restart_policy:
        condition: any

Save each file below into a folder, then run kubectl apply -f .
Written for k3s, but works on any cluster: bind mounts use hostPath, named volumes get a persistent volume claim, and ports are exposed via a LoadBalancer service.

swag-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: swag
  labels:
    app: swag
spec:
  replicas: 1
  selector:
    matchLabels:
      app: swag
  template:
    metadata:
      labels:
        app: swag
    spec:
      containers:
        - name: swag
          image: linuxserver/swag:latest
          env:
            - name: PUID
              value: '1000'
            - name: PGID
              value: '1000'
            - name: TZ
              value: Etc/UTC
            - name: URL
              value: example.com
            - name: VALIDATION
              value: http
            - name: SUBDOMAINS
              value: www,
            - name: CERTPROVIDER
              value: ''
            - name: CERT_PROFILE
              value: ''
            - name: DNSPLUGIN
              value: cloudflare
            - name: PROPAGATION
              value: ''
            - name: EMAIL
              value: ''
            - name: ONLY_SUBDOMAINS
              value: 'false'
            - name: EXTRA_DOMAINS
              value: ''
            - name: STAGING
              value: 'false'
            - name: DISABLE_F2B
              value: ''
            - name: SWAG_AUTORELOAD
              value: ''
            - name: SWAG_AUTORELOAD_WATCHLIST
              value: ''
          ports:
            - containerPort: 443
              protocol: TCP
            - containerPort: 80
              protocol: TCP
            - containerPort: 443
              protocol: UDP
          volumeMounts:
            - name: swag-data-0
              mountPath: /config
      volumes:
        - name: swag-data-0
          hostPath:
            path: /srv/lsio/swag/config

swag-service.yaml

apiVersion: v1
kind: Service
metadata:
  name: swag
spec:
  type: LoadBalancer
  selector:
    app: swag
  ports:
    - name: 443-tcp
      port: 443
      targetPort: 443
      protocol: TCP
    - name: 80-tcp
      port: 80
      targetPort: 80
      protocol: TCP
    - name: 443-udp
      port: 443
      targetPort: 443
      protocol: UDP

Save this file as ~/.config/containers/systemd/swag.container

[Unit]
Description=Swag

[Container]
Image=linuxserver/swag:latest
ContainerName=swag
PublishPort=443:443/tcp
PublishPort=80:80/tcp
PublishPort=443:443/udp
Environment=PUID=1000
Environment=PGID=1000
Environment=TZ=Etc/UTC
Environment=URL=example.com
Environment=VALIDATION=http
Environment=SUBDOMAINS=www,
Environment=CERTPROVIDER=
Environment=CERT_PROFILE=
Environment=DNSPLUGIN=cloudflare
Environment=PROPAGATION=
Environment=EMAIL=
Environment=ONLY_SUBDOMAINS=false
Environment=EXTRA_DOMAINS=
Environment=STAGING=false
Environment=DISABLE_F2B=
Environment=SWAG_AUTORELOAD=
Environment=SWAG_AUTORELOAD_WATCHLIST=
Volume=/srv/lsio/swag/config:/config

[Service]
Restart=always

[Install]
WantedBy=default.target

Then reload systemd and start the service:

systemctl --user daemon-reload
systemctl --user start swag

For a system-wide service, use /etc/containers/systemd/ and drop --user.

For more installation options, see the Documentation in our GitHub repo

linuxserver/swag

This readme has been truncated from the full version found HERE

SWAG - Secure Web Application Gateway (formerly known as letsencrypt, no relation to Let's Encrypt™) sets up an Nginx webserver and reverse proxy with php support and a built-in certbot client that automates free SSL server certificate generation and renewal processes (Let's Encrypt and ZeroSSL). It also contains fail2ban for intrusion prevention.

Application Setup

Validation and initial setup

  • Before running this container, make sure that the url and subdomains are properly forwarded to this container's host, and that port 443 (and/or 80) is not being used by another service on the host (NAS gui, another webserver, etc.).
  • If you need a dynamic dns provider, you can use the free provider duckdns.org where the URL will be yoursubdomain.duckdns.org and the SUBDOMAINS can be www,ftp,cloud with http validation, or wildcard with dns validation. You can use our duckdns image to update your IP on duckdns.org.
  • For http validation, port 80 on the internet side of the router should be forwarded to this container's port 80
  • For dns validation, make sure to enter your credentials into the corresponding ini (or json for some plugins) file under /config/dns-conf
Cloudflare provides free accounts for managing dns and is very easy to use with this image. Make sure that it is set up for "dns only" instead of "dns + proxy" Google dns plugin is meant to be used with "Google Cloud DNS", a paid enterprise product, and not for "Google Domains DNS" DuckDNS only supports two types of DNS validated certificates (not both at the same time):
1. Certs that only cover your main subdomain (ie. `yoursubdomain.duckdns.org`, leave the `SUBDOMAINS` variable empty)
2. Certs that cover sub-subdomains of your main subdomain (ie. `*.yoursubdomain.duckdns.org`, set the `SUBDOMAINS` variable to `wildcard`)
  • --cap-add=NET_ADMIN is required for fail2ban to modify iptables
  • After setup, navigate to https://example.com to access the default homepage (http access through port 80 is disabled by default, you can enable it by editing the default site config at /config/nginx/site-confs/default.conf).
  • Certs are checked twice daily using ACME Renewal Information (ARI) to determine the optimal renewal window. If your cert is about to expire, check the logs under /config/log/letsencrypt to see why the renewals have been failing.

Certbot Plugins

SWAG includes many Certbot plugins out of the box, but not all plugins can be included. If you need a plugin that is not included, the quickest way to have the plugin available is to use our Universal Package Install Docker Mod.
Set the following environment variables on your container:
DOCKER_MODS=linuxserver/mods:universal-package-install
INSTALL_PIP_PACKAGES=certbot-dns-<plugin>

Set the required credentials (usually found in the plugin documentation) in /config/dns-conf/<plugin>.ini. It is recommended to attempt obtaining a certificate with STAGING=true first to make sure the plugin is working as expected.

Security and password protection

  • The container detects changes to url and subdomains, revokes existing certs and generates new ones during start.
  • Per RFC7919, the container is shipping ffdhe4096 as the dhparams.pem.
  • If you'd like to password protect your sites, you can use htpasswd. Run the following command on your host to generate the htpasswd file docker exec -it swag htpasswd -c /config/nginx/.htpasswd <username>
  • You can add multiple user:pass to .htpasswd. For the first user, use the above command, for others, use the above command without the -c flag, as it will force deletion of the existing .htpasswd and creation of a new one
  • You can also use ldap auth for security and access control. A sample, user configurable ldap.conf is provided, and it requires the separate image linuxserver/ldap-auth to communicate with an ldap server.

Site config and reverse proxy

  • The default site config resides at /config/nginx/site-confs/default.conf. Feel free to modify this file, and you can add other conf files to this directory. However, if you delete the default file, a new default will be created on container start.
  • Preset reverse proxy config files are added for popular apps. See the README.md file under /config/nginx/proxy_confs for instructions on how to enable them. The preset confs reside in and get imported from this repo.
  • If you wish to hide your site from search engine crawlers, you may find it useful to add this configuration line to your site config, within the server block, above the line where ssl.conf is included
add_header X-Robots-Tag "noindex, nofollow, nosnippet, noarchive"; This will ask Google et al not to index and list your site. Be careful with this, as you will eventually be de-listed if you leave this line in on a site you wish to be present on search engines
  • If you wish to redirect http to https, you must expose port 80

Using certs in other containers

  • This container includes auto-generated pfx and private-fullchain-bundle pem certs that are needed by other apps like Emby and Znc.
To use these certs in other containers, do either of the following: 1. (Easier) Mount the container's config folder in other containers (ie. -v /path-to-swag-config:/swag-ssl) and in the other containers, use the cert location /swag-ssl/keys/letsencrypt/ 2. (More secure) Mount the SWAG folder etc that resides under /config in other containers (ie. -v /path-to-swag-config/etc:/swag-ssl) and in the other containers, use the cert location /swag-ssl/letsencrypt/live/<your.domain.url>/ (This is more secure because the first method shares the entire SWAG config folder with other containers, including the www files, whereas the second method only shares the ssl certs) These certs include: 1. cert.pem, chain.pem, fullchain.pem and privkey.pem, which are generated by Certbot and used by nginx and various other apps 2. privkey.pfx, a format supported by Microsoft and commonly used by dotnet apps such as Emby Server (no password) 3. priv-fullchain-bundle.pem, a pem cert that bundles the private key and the fullchain, used by apps like ZNC

Using fail2ban

  • This container includes fail2ban set up with 5 jails by default:
1. nginx-http-auth 2. nginx-badbots 3. nginx-botsearch 4. nginx-deny 5. nginx-unauthorized
  • To enable or disable other jails, modify the file /config/fail2ban/jail.local
  • To modify filters and actions, instead of editing the .conf files, create .local files with the same name and edit those because .conf files get overwritten when the actions and filters are updated. .local files will append whatever's in the .conf files (ie. nginx-http-auth.conf --> nginx-http-auth.local)
  • You can check which jails are active via docker exec -it swag fail2ban-client status
  • You can check the status of a specific jail via docker exec -it swag fail2ban-client status <jail name>
  • You can unban an IP via docker exec -it swag fail2ban-client set <jail name> unbanip <IP>
  • A list of commands for fail2ban-client can be found here

Updating configs

  • This container creates a number of configs for nginx, proxy samples, etc.
  • Config updates are noted in the changelog but not automatically applied to your files.
  • If you have modified a file with noted changes in the changelog:
1. Keep your existing configs as is (not broken, don't fix) 2. Review our repository commits and apply the new changes yourself 3. Delete the modified config file with listed updates, restart the container, reapply your changes
  • If you have NOT modified a file with noted changes in the changelog:
1. Delete the config file with listed updates, restart the container

QUIC support

This image supports QUIC (also known as HTTP/3) but it must be explicitly enabled in each proxy conf, and the default conf, because if the listener is enabled and you don't expose 443/UDP, it can break connections with some browsers.
To enable QUIC, expose 443/UDP to your clients, then uncomment both QUIC listeners in all of your active proxy confs, as well as the default conf, and restart the container.
You should also uncomment the Alt-Svc header in your ssl.conf so that browsers are aware that you offer QUIC connectivity.
It is recommended to increase the UDP send/recieve buffer on the host by setting the net.core.rmem_max and net.core.wmem_max sysctls. Suggested values are 4-16Mb (4194304-16777216 bytes). For persistence between reboots use /etc/sysctl.d/.

Migration from the old linuxserver/letsencrypt image

Please follow the instructions on this blog post.

Usage

docker run -d \
  --name=swag \
  --cap-add=NET_ADMIN \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e URL=example.com \
  -e VALIDATION=http \
  -e SUBDOMAINS=www, `#optional` \
  -e CERTPROVIDER= `#optional` \
  -e CERT_PROFILE= `#optional` \
  -e DNSPLUGIN=cloudflare `#optional` \
  -e PROPAGATION= `#optional` \
  -e EMAIL= `#optional` \
  -e ONLY_SUBDOMAINS=false `#optional` \
  -e EXTRA_DOMAINS= `#optional` \
  -e STAGING=false `#optional` \
  -e DISABLE_F2B= `#optional` \
  -e SWAG_AUTORELOAD= `#optional` \
  -e SWAG_AUTORELOAD_WATCHLIST= `#optional` \
  -p 443:443 \
  -p 80:80 `#optional` \
  -p 443:443/udp `#optional` \
  -v /path/to/swag/config:/config \
  --restart unless-stopped \
  lscr.io/linuxserver/swag:latest

Serve Swag on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxying swag.example.com to https://Swag:443

Add this to your Caddyfile

swag.example.com {
	reverse_proxy https://Swag:443 {
		transport http {
			tls_insecure_skip_verify
		}
	}
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs Swag
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:443 failed: port is already allocated", something else on your server is using that port.

  • Find what's using it: sudo ss -tlnp | grep :443
  • Stop the other service, or pick a different host port. In 443:443 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

  • Use your server's real IP: https://your-server-ip:443. The 0.0.0.0 link Portainer shows isn't a real address.
  • Give it a minute after first deploy, Swag can take a while to initialise.
  • Make sure your firewall allows the port, e.g. sudo ufw allow 443

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

  • Fix the ownership: sudo chown -R 1000:1000 /srv/lsio/swag/config
  • Or set the PUID and PGID variables (defaults 1000:1000) to match your own user, found with id $USER

Image won't pull

Test the pull directly on the host: docker pull linuxserver/swag:latest

  • "manifest unknown" means the tag no longer exists. This template uses latest, so try pinning a specific version instead.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • This image supports: amd64, arm64
  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect Swag --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Required settings are blank

CERTPROVIDER, CERT_PROFILE, PROPAGATION, EMAIL, EXTRA_DOMAINS, DISABLE_F2B, SWAG_AUTORELOAD, SWAG_AUTORELOAD_WATCHLIST have no default value, and Swag may crash or misbehave if left empty.

  • Fill them in on the deploy screen before hitting deploy.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

Similar apps

Nginx Nginx Reverse Proxy