SWAG
Last updated
Last updated
SWAG - Secure Web Application Gateway (formerly known as LetsEncrypt, no relation to Let's Encrypt™) sets up an Nginx web server 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.
Head to the community apps and search for "SWAG"
Now click on the install button and we will fill in the template.
Here we can name the container, to keep things simple we will keep the name as swag
This is where you can choose the image for the container, we will leave this as default.
We can choose which network to add this container to, we suggest adding this container to the same custom docker network as all your other containers, this will make things simpler down the road.
Now we can choose the HTTP port, all you need to do is make sure the port is free on the host. For this example, we will be using 8001.
Here we can choose the HTTPS port, all you need to do is make sure the port is free on the host. For this example, we will be using 44301.
While applying for certs it is advised that you add your email so that you can be notified when your certs need renewing. This field is where we will add that email.
Now we can add the main domain, in this field add your full root domain.
While applying for certificates we want to make sure all of our subdomains will be covered without having to type them all in. To achieve this we simply add wildcard to this field and it will cover all your subdomains.
Most users will want to add an app to their root domain so in this field we will add the value false. If you do not want a cert for your root domain and only for all the subdomains then you can set this to true.
For cert validation here we will choose DNS. There are a few options but we find it much easier and quicker to go for the DNS validation.
This will be your DNS provider. SWAG supports many DNS providers and if you are interested then you can check out the SWAG documentation here to see which are supported. If you have a different provider, the method is much the same but you will just have to add your own provider here and also choose a different file later on. In this example, we will be using Cloudflare.
This is where all the config files will be stored once the container starts up.
Some of you may want to support more than one domain. This is possible and within SWAG it is very easy to add more and have the certs created for them automatically. You simply add all your extra domains in this field and separate them with a comma.
Staging is used to test out applying for certs. It can be very useful if you are having issues to make sure you do not get API limited for applying for certs too quickly in a short amount of time. These certs are not meant to be permeant though so we will just go straight for the real certs by setting this option to false.
IF you are using DuckDNS then this field is where you would add your token for DNS validation.
If required you can override the default propagation timing but we have found the defaults are perfectly fine especially for Cloudflare.
Now simply click apply and your container will be deployed.
To make this easier for you, we are going to create a wildcard CNAME. In the past, we have covered creating proxied DNS records so in this guide, we will cover creating DNS only records. The benefit to this is that we can add a wildcard CNAME pointing all subdomains to the root domain. This means we will never have to add another CNAME to the domain while adding more apps to your Unraid server.
Simply add an A record that points to your public IP and set the record to be "DNS Only".
Next, add a CNAME with the record pointing to "*" and again set this to DNS only.
Now any subdomain you try to access will be pointed to your SWAG. This means we will never have to add another CNAME each time you add an app to your Unraid.
If you would like to mask your server IP from people who know your domain you can proxy your DNS records to run through Cloudflare's servers. This also gives you the added DDOS protection that Cloudflare provides for free.
For this, you will add your A record as above but you will select to proxy the DNS record.
You will then have to set up a CNAME for every single app that you would like to use on your domain. See the screenshot below as an example:
Since we have chosen to validate the domains via DNS provider we will have to get an API token to allow the validation to take place.
This will be slightly different for each provider. For this example, we will use Cloudflare.
If you go to your Cloudflare and log in, then in the top right corner click the little man, and then choose "My Profile". This will take you to your account settings.
Now choose the top tab "API Tokens". Click "Create new API Token" and then change the zones resources to include all zones (you can specify just a single domain here if you like).
Click "Continue to summary" and then "Create Token". Copy this token and keep it somewhere safe for now.
Now we will set up the DNS validation for SWAG by adding your credentials to a file within the appdata folder.
To edit this file we will go from the command line and use the tool nano to edit the file.
We can now add the Cloudflare email address we use to log in and then also paste in the token you just created. This will allow swag to access your account to automatically validate your domain to get a let's encrypt cert for SSL.
Since we are using the api token and not the api key, we need to make sure we comment out the api key line and the email line by adding a "#" at the beginning of each line.
We will then have to uncomment out the api token line and paste your token at the end of this line (replacing the fake token placeholder). Below is an example:
Press ctrl + x and then press enter to save and exit.
Now we have added all the credentials needed it would be worth restarting the container to apply the new settings.
You can either do this in the UI or from the command line with the following command.
Now check your SWAG logs and you should see it getting new certs for your domain/s.
The Linuxserver team has been hard at work with their containers and has actually added a few "Docker Mods" to each of them.
To improve on the functionality of their SWAG container we will be adding a few docker mods.
To begin with, we will be adding "Universal Docker" to the SWAG container. This is used for a few of the docker mods and so it's good to install this first.
To add docker mods we will have to edit the SWAG template from within Unraid.
Find your SWAG container and then click edit to edit the template.
We are now going to add an environment variable with the key DOCKER_MODS. This will be where we add all of the docker mods.
Once you are in the template, scroll to the bottom and click on the "Add another Path, Port, Variable, Label or Device".
Now going select to add a variable and fill in the fields as per the screenshot below.
Make sure to add this line to the value to add the universal-docker mod:
You can now click "ADD" and this variable will be added to your template.
A lot of the time we will want clients' real IP addresses but they will often come from Cloudflare so we want to make sure we are getting the correct IP by passing through a certain argument. SWAG will do this for us by simply running the docker mod "Cloudflare Real IP".
Since we did most of the work with the last docker mod, all we need to do now is add to the already existing variable DOCKER_MODS.
Scroll down to this variable and in the field, you can copy and paste the following to the end (make sure to include the "|" between the docker mods, this is used to separate the docker mod's and install them all correctly):
You can now apply this to your container so that it will run the container with the new settings. The container will now create a new file for you here /mnt/user/appdata/swag/nginx/cf_real-ip.conf
Once the new container has deployed we will want to make sure the container uses the IP's in this file.
To do this we will edit the nginx.conf file to include the newly created file. We will do this again using the command line file editing tool nano:
You will need to add the following lines to your http section of the config file
For a quick example of what this file could look like, here is an example without any of the comments:
For a quick example of what this file could look like, here is an example without any of the comments:
Press ctrl + x and then press enter to save and exit.
You will now want to restart your container to apply the new settings.
This can either be done in the Unraid UI or typing the following command in the command line:
When making edits within the SWAG config files it can be annoying having to restart the container all the time. Luckily Linuxserver has us covered and has made a docker-mod to auto reload Nginx when it detects a file has been changed.
To add this docker mod it is much the same as before.
Go into Unraid, find your SWAG container, edit the template, scroll down the DOCKER_MODS variable we added and paste the following at the end of the field:
Click apply to add the new docker mod to your container.
Each time you change a config file the container will now check that the change is valid. If the change is valid it will reload Nginx with the new settings.
The following is the list of files and folders that the container will monitor for changes:
/config/nginx/authelia-location.conf
/config/nginx/authelia-server.conf
/config/nginx/geoip2.conf
/config/nginx/ldap.conf
/config/nginx/nginx.conf
/config/nginx/proxy-confs
/config/nginx/proxy.conf
/config/nginx/site-confs
/config/nginx/ssl.conf
If you would like to add any more files or folders to the watchlist you can simply add another variable to the SWAG container template.
Once you are in the template, scroll to the bottom and click on the "Add another Path, Port, Variable, Label or Device".
Select to add a variable and fill in the fields as per the screenshot below.
For this example, we will monitor both the custom.conf file and the /customfolder folder:
Note
Make sure to separate them with a "|"
This docker mod is called "auto proxy" and gives SWAG the ability to auto-detect running containers via labels and automatically enable reverse proxy for them.
Important
For this docker mod, make sure that the universal docker mod (above) has already been installed.
As we stated earlier in the guide, it is preferred to run this container on the same custom docker network as all your other apps. For this docker mod to work that step is vital and if not set up correctly, it will not work.
Since this docker mod uses the docker API to locate new apps to add to the reverse proxy, we need to now give the container more permissions.
Giving docker API access to a publicly accessible docker container is a security liability and so it would be preferred to try and limit the amount of access this container has to the API. We can achieve this by using a proxy container that will allow limited access to the Docker API and only allow through what we need to make things work.
For this, we are going to use a docker container by Tecnativa called "docker-socket-proxy"
Head over to the community apps and search for "dockersocket" and click install.
The only part you need to change in this template is to add it to your custom docker network that every other container should also be on.
Once you have added it to your docker network, simply click "apply" to install it.
Now head over to your SWAG container and edit the template.
Once you are in the template, scroll to the bottom and click on the "Add another Path, Port, Variable, Label or Device".
We are now going to select to add a variable and fill in the fields as per the screenshot below.
For the key field, we will be using DOCKER_HOST and for the value field, we need to add the container name for the docker socket proxy container, in this example that is dockersocket
The SWAG container will now be able to retrieve info on other containers (read-only access), but will not be able to spin up other containers or run any commands via the docker API.
We can now add the docker mod to the container by pasting the following to the DOCKER_MODS variable:
Click "Save", scroll to the bottom of the template and click "Apply" to deploy the container again.
Warning - Insecure Method
Allowing a container direct access to docker.sock is insecure and could make your system vulnerable to attack. Please read the following post to see more about the vulnerabilities of sharing docker.sock with docker containers and how it could compromise your server.
The Danger of Exposing docker.sock
To do this we need to add a new path mapping.
In your SWAG container template, scroll to the bottom and select "Add another Path, Port, Variable, Label or Device" and choose "Path" from the drop-down.
You will now have to add the following to both the host and container path mappings as per the screenshot below:
We can now add the docker mod to the container by pasting the following to the DOCKER_MODS variable:
Click "Save", scroll to the bottom of the template and click "apply" to deploy the container again.
Now, to add an app to the reverse proxy, we simply just add a single extra label to each app.
Open an app template to test adding it to your reverse proxy.
Scroll down to the bottom and click "Add another Path, Port, Variable, Label or Device".
Select "Label" from the drop-down and fill in the fields as per the screenshot below:
Click Save, then apply your changes to the template to re-deploy the container.
This container should now be accessible via your app subdomain/domain.
Important
To benefit from curated pre-set proxy confs we provide, the container name must match the container names that are suggested in our readme examples (ie. radarr and not Radarr-4K).
swag=enable - required for auto-detection
swag_address=containername - optional - overrides upstream app address. Can be set to an IP or a DNS hostname. Defaults to container name.
swag_port=80 - optional - overrides internal exposed port
swag_proto=http - optional - overrides internal proto (defaults to http)
swag_url=containername.domain.com - optional - overrides server_name (defaults to containername.*)
swag_auth=authelia - optional - enables auth methods (options are authelia, ldap and http for basic http auth)
swag_auth_bypass=/api,/othersubfolder - optional - bypasses auth for selected subfolders. Comma separated, no spaces.
Another method for reverse proxying containers can be to manually edit one of the many templates Linuxserver has created from within the docker container.
These config's for the subdomains are kept here /mnt/user/appdata/swag/nginx/proxy-confs/
To get an idea of all the templates Linuxserver has created for us you can run the following command from the Unraid console:
To enable any app we simply change the filename from ...subdomain.conf.sample to ...subdomain.conf.
We can do this in the command line very easily. For this example, we will do it for Sonarr.
We will use the "mv" command which essentially moves a file from A to B but if we just give the new location as a changed filename then all it does is change the filename of the existing file.
Paste the following command into the Unraid console to allow Sonarr to be reverse proxied:
If you do have "Auto Reload" enabled, SWAG will now reload Nginx and your subdomain will be available.
If you do not have "Auto Reload" enabled you will have to restart the SWAG container. This can either be done in the Unraid UI or by typing the following command in the command line:
Before enabling Authelia in the SWAG configurations we need to make sure Authelia is set. SWAG uses the subfolder method by default for Authelia instead of subdomain (domain.com/authelia as opposed to authelia.domain.com).
To allow Authelia to work with subfolders and sync up with the swag settings, we may need to make a quick adjustment to our Authelia configuration.yml
Making this quick edit will allow Authelia to use subfolders and will sync up the path settings with what SWAG uses by default. All we need to do is add "authelia" to the path: variable under the server: settings in the Authelia configuration.yml. See the configuration snippet below as an example of how it should look (the edit on line 4.)
To save and close the configuration, now press ctrl + x and then press enter .
To enable Authelia to any app that you are using, you can simply add a single label to each container you would like to protect.
Find the app that you would like to protect, click edit to update the template, scroll down to the bottom and click "Add another Path, Port, Variable, Label or Device".
Select "Label" from the drop-down and fill in the fields as per the screenshot below:
Click save and apply to re-deploy the container again but this time with Authelia's Protection.
If you would like to bypass /api of any single container from Authelia's protection, you can add another label to each app:
If you have used the manual method to reverse proxy your apps then you will want to use this method for enabling Authelia for your applications.
After you have moved the template from ...subdomain.conf.sample to ...subdomain.confyou will then want to edit the config file to make some minor adjustments. For this example, we will make those edits for the app radarr from within the Unraid command line with the text editor nano.
To add Authelia to this app, all we need to do is uncomment two lines (remove the "#" at the beginning of the line) where it says "# enable for Authelia ". See the example below at line 15 and line 27:
If you do have "Auto Reload" enabled, SWAG will now reload Nginx and your subdomain will be available.
If you do not have "Auto Reload" enabled you will have to restart the SWAG container. This can either be done in the Unraid UI or by typing the following command in the command line:
For any issues, please head over to Linuxserver own troubleshooting section as a first stop as it should cover you for most cases.
For anything not covered here or in the official docs please join our Discord! We'd love to have you.
We hope you enjoyed this guide. It was conceptualized, written, and implemented by our Community Leader Hawks.
Big thanks to Linuxserver who created and continues to maintain this fantastic container with all of the useful docker mods.
Also, big thanks to our community member and community developer GilbN who helped when we got stuck implementing this for the first time, go to his profile and show him some love.
Our work sometimes takes months to research and develop. If you want to help support us please consider:
Liking and Subscribing to our Youtube channel
Joining our Discord server
Becoming a paid member on our IBRACORP website
Donating via Paypal
Thank you for being part of our community!
