Portainer Templates logo

Portainer Templates

Swag Swag

Container

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: 91.1M
Architecture: amd64, arm64
Image size: 153 MB
Latest: 5.7.0
User: linuxserver
Created: Aug 03, 2020
Updated: 1 day 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

Standalone Install

Select an install method, to see config/commands for deploying Swag

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  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 Swag, fill in any config options, and hit Deploy

Template Import URL

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

More install options in our documentation.

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.

A single container

Swag runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.

The app image

An image is the app packed up ready to go, everything Swag needs bundled into one download. This template pulls linuxserver/swag:latest, which Docker fetches once (about 153 MB) and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. Swag's comes from Docker Hub, published by linuxserver.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Newest right now is 5.7.0. Pin a specific tag if you would rather stay on one version.

Which machines it runs on

Every image is built for particular CPU types. This one ships for amd64, arm64, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.

Ports

A port is the door the app answers on. A mapping like 443:443 means it's reachable on port 443 of your server, where the left number is yours to change and the right one belongs to the app. Once it's running, open https://your-server-ip:443 in a browser. It opens:

  • 443:443, likely the web interface
  • 80:80, likely the web interface
  • 443:443 over UDP, likely the web interface

Volumes

A volume is where Swag keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /config from /srv/lsio/swag/config on the host

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Swag takes 17 of them, and 8 need a value before it'll start properly:

  • PUID, defaults to 1000. Run 'id [USER]' for the owner of the host volume directories to get the UID to use here.
  • PGID, defaults to 1000. Run 'id [USER]' for the owner of the host volume directories to get the GID to use here.
  • TZ, defaults to Etc/UTC. Specify a timezone to use, see this list.
  • URL, defaults to example.com. Top url you have control over (e.g. example.com if you own it, or customsubdomain.example.com if dynamic dns).
  • VALIDATION, defaults to http. Certbot validation method to use, options are http or dns (dns method also requires DNSPLUGIN variable set).
  • SUBDOMAINS, defaults to www,. Subdomains you'd like the cert to cover (comma separated, no spaces) ie. www,ftp,cloud. For a wildcard cert, set this exactly to wildcard (wildcard cert is available via dns validation only) [OPTIONAL]
  • CERTPROVIDER, needs a value. Optionally define the cert provider. Set to zerossl for ZeroSSL certs (requires existing ZeroSSL account and the e-mail address entered in EMAIL env var). Otherwise defaults to Let's Encrypt. [OPTIONAL]
  • CERT_PROFILE, needs a value. Optionally define a cert profile to use for cert generation. This is useful if you want to use a custom cert profile instead of the default one. Currently only supported for Let's Encrypt. See https://letsencrypt.org/docs/profiles/ [OPTIONAL]
  • DNSPLUGIN, defaults to cloudflare. Required if VALIDATION is set to dns. Options are acmedns, aliyun, azure, bunny, cloudflare, cpanel, desec, digitalocean, directadmin, dnsimple, dnsmadeeasy, dnspod, do, domeneshop, dreamhost, duckdns, dynu, freedns, gandi, gehirn, glesys, godaddy, google, he, hetzner, hetzner-cloud, infomaniak, inwx, ionos, linode, loopia, luadns, mijn-host, namecheap, netcup, njalla, nsone, ovh, porkbun, rfc2136, route53, sakuracloud, standalone, transip, and vultr. Also need to enter the credentials into the corresponding ini (or json for some plugins) file under /config/dns-conf. [OPTIONAL]
  • PROPAGATION, needs a value. Optionally override (in seconds) the default propagation time for the dns plugins. [OPTIONAL]
  • EMAIL, needs a value. Optional e-mail address used for cert expiration notifications (Required for ZeroSSL). [OPTIONAL]
  • ONLY_SUBDOMAINS, defaults to false. If you wish to get certs only for certain subdomains, but not the main domain (main domain may be hosted on another machine and cannot be validated), set this to true [OPTIONAL]
  • EXTRA_DOMAINS, needs a value. Additional fully qualified domain names (comma separated, no spaces) ie. example.net,subdomain.example.net,.example.org [OPTIONAL]
  • STAGING, defaults to false. Set to true to retrieve certs in staging mode. Rate limits will be much higher, but the resulting cert will not pass the browser's security test. Only to be used for testing purposes. [OPTIONAL]
  • DISABLE_F2B, needs a value. Set to true to disable the Fail2ban service in the container, if you're already running it elsewhere or using a different IPS. [OPTIONAL]
  • SWAG_AUTORELOAD, needs a value. Set to true to enable automatic reloading of confs on change without stopping/restarting nginx. Your filesystem must support inotify. This functionality was previously offered via mod. [OPTIONAL]
  • SWAG_AUTORELOAD_WATCHLIST, needs a value. A pipe-separated list of additional folders for auto reload to watch in addition to /config/nginx [OPTIONAL]

Restart policy

The restart policy here is unless-stopped, so Docker restarts Swag after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Users and permissions

The PUID and PGID settings tell it which user and group to act as on your host. Point them at your own account (find yours with id $USER) so the files it writes into your mounted folders come out owned by you rather than root.

Networking

Nothing custom is set, so Swag sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container Swag. That's what you'll spot in the containers list and use in commands like docker logs Swag.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Swag up. Add the template list to Portainer once, then deploying Swag is a click rather than a wall of config.