SWAG setup

The goal of this guide is to give you ideas on what can be accomplished with the LinuxServer SWAG docker image and to get you started. We will explain some of the basic concepts and limitations, and then we'll provide you with common examples. If you have further questions, you can ask on our forum or join our Discord for conversations: https://discord.gg/YWrKVTn
Table of Contents
​Introduction​
​What are SSL certs?​
​What is Let's Encrypt (and/or ZeroSSL)?​
​Creating a SWAG container​
​Docker cli​
​Docker compose​
​Authorization method​
​Cert provider (Let's Encrypt vs ZeroSSL)​
​Port forwards​
​Docker networking​
​Container setup examples​
​Create container via http validation​
​Create container via dns validation with a wildcard cert​
​Create container via duckdns validation with a wildcard cert​
​Web hosting examples​
​Simple html web page hosting​
​Hosting a Wordpress site​
​Reverse Proxy​
​Preset proxy confs​
​Understanding the proxy conf structure​
​Subdomain proxy conf​
​Subfolder proxy conf​
​Ombi subdomain reverse proxy example​
​Nextcloud subdomain reverse proxy example​
​Plex subfolder reverse proxy example​
​Using Heimdall as the home page at domain root​
​Troubleshooting​
​Common errors​
​404​
​502​
​Final Thoughts​
​How to Request Support​
Introduction
What are SSL certs?
SSL certs allow users of a service to communicate via encrypted data transmitted up and down. Third party trusted certs also allow users to make sure that the remote service they are connecting to is really who they say they are and not someone else in the middle. When we run a web server for reasons like hosting websites or reverse proxying services on our own domain, we need to set it up with third party trusted ssl certs so client browsers trust it and communicate with it securely. When you connect to a website with a trusted cert, most browsers show a padlock icon next to the address bar to indicate that. Without a trusted cert (ie. with self signed cert) most browsers show warning pages or may block access to the website as the website identity cannot be confirmed via a trusted third party.
What is Let's Encrypt (and/or ZeroSSL)?
In the past, the common way to get a trusted ssl cert was to contact one of the providers, send them the relevant info to prove ownership of a domain and pay for the service. Nowadays, with Let's Encrypt and ZeroSSL, one can get free certs via automated means.
The SWAG docker image, published and maintained by LinuxServer.io, makes setting up a full-fledged web server with auto generated and renewed ssl certs very easy. It is essentially an nginx webserver with php7, fail2ban (intrusion prevention) and Let's Encrypt cert validation built-in. It is just MySQL short of a LEMP stack and therefore is best paired with our MariaDB docker image.
Creating a SWAG container
Most of the initial settings for getting a webserver with ssl certs up are done through the docker run/create or compose yaml parameters. Here's a list of all the settings available including the optional ones. It is safe to remove unnecessary parameters for different scenarios.
docker cli
1
docker create \
2
  --name=swag \
3
  --cap-add=NET_ADMIN \
4
  -e PUID=1000 \
5
  -e PGID=1000 \
6
  -e TZ=Europe/London \
7
  -e URL=yourdomain.url \
8
  -e SUBDOMAINS=www, \
9
  -e VALIDATION=http \
10
  -e CERTPROVIDER= `#optional` \
11
  -e DNSPLUGIN=cloudflare `#optional` \
12
  -e DUCKDNSTOKEN=<token> `#optional` \
13
  -e EMAIL=<e-mail> `#optional` \
14
  -e ONLY_SUBDOMAINS=false `#optional` \
15
  -e EXTRA_DOMAINS=<extradomains> `#optional` \
16
  -e STAGING=false `#optional` \
17
  -p 443:443 \
18
  -p 80:80 `#optional` \
19
  -v </path/to/appdata/config>:/config \
20
  --restart unless-stopped \
21
  lscr.io/linuxserver/swag
Copied!
docker-compose
Compatible with docker-compose v2 schemas.
1
---
2
version: "2.1"
3
services:
4
  swag:
5
    image: lscr.io/linuxserver/swag
6
    container_name: swag
7
    cap_add:
8
      - NET_ADMIN
9
    environment:
10
      - PUID=1000
11
      - PGID=1000
12
      - TZ=Europe/London
13
      - URL=yourdomain.url
14
      - SUBDOMAINS=www,
15
      - VALIDATION=http
16
      - CERTPROVIDER= #optional
17
      - DNSPLUGIN=cloudflare #optional
18
      - DUCKDNSTOKEN=<token> #optional
19
      - EMAIL=<e-mail> #optional
20
      - ONLY_SUBDOMAINS=false #optional
21
      - EXTRA_DOMAINS=<extradomains> #optional
22
      - STAGING=false #optional
23
    volumes:
24
      - </path/to/appdata/config>:/config
25
    ports:
26
      - 443:443
27
      - 80:80 #optional
28
    restart: unless-stopped
Copied!
Authorization method
Our image currently supports three different methods to validate domain ownership:
http:
Let's Encrypt (acme) server connects to domain on port 80
Can be owned domain or a dynamic dns address
dns:
Let's Encrypt (acme) server connects to dns provider
Api credentials and settings entered into ini files under /config/dns-conf/
Supports wildcard certs
Need to have own domain name (non-free)
duckdns:
Let's Encrypt (acme) server connects to DuckDNS
Supports wildcard certs (only for the sub-subdomains)
No need for own domain (free)
The validation is performed when the container is started for the first time. Nginx won't be up until ssl certs are successfully generated.
The certs are valid for 90 days. The container will check the cert expiration status every night and if they are to expire within 30 days, it will attempt to auto-renew. If your certs are about to expire in less than 30 days, check the logs under /config/log/letsencrypt to see why the auto-renewals failed.
Cert Provider (Let's Encrypt vs ZeroSSL)
As of January 2021, SWAG supports getting certs validated by either Let's Encrypt or ZeroSSL. Both services use the ACME protocol as the underlying method to validate ownership. Our Certbot client in the SWAG image is ACME compliant and therefore supports both services.
Although very similar, ZeroSSL does (at the time of writing) have a couple of advantages over Let's Encrypt:
ZeroSSL provides unlimited certs via ACME and has no rate limits or throttling (it's quite common for new users to get throttled by Let's Encrypt due to multiple unsuccessful attempts to validate)
ZeroSSL provides a web interface that allows users to list and manage the certs they have received
SWAG currently defaults to Let's Encrypt as the cert provider so as not to break existing installs, however users can override that behavior by setting the environment variable CERTPROVIDER=zerossl to retrieve a cert from ZeroSSL instead. The only gotcha is that ZeroSSL requires the EMAIL env var to be set so the certs can be tied to a ZeroSSL account for management over their web interface.
Port forwards
Port 443 mapping is required for access through https://domain.com. However, you don't necessarily need to have it listen on port 443 on the host server. All that is needed is to have port 443 on the router (wan) somehow forward to port 443 inside the container, while it can go through a different port on the host.
For instance, it is ok to have port 443 on router (wan) forward to port 444 on the host, and then map port 444 to port 443 in docker run/create or compose yml.
Port 80 forwarding is required for http validation only. Same rule as above applies, and it's OK to go from 80 on the router to 81 on the host, mapped to 80 in the container.
Docker networking
SWAG container happily runs with bridge networking. However, the default bridge network in docker does not allow containers to connect each other via container names used as dns hostnames. Therefore, it is recommended to first create a user defined bridge network and attach the containers to that network.
If you are using docker-compose, and your services are on the same yaml, you do not need to do this, because docker-compose automatically creates a user defined bridge network and attaches each container to it as long as no other networking option is defined in their config.
For the below examples, we will use a network named lsio. We can create it via docker network create lsio. After that, any container that is created with --net=lsio can ping each other by container name as dns hostname.
Keep in mind that dns hostnames are meant to be case-insensitive, however container names are case-sensitive. For container names to be used as dns hostnames in nginx, they should be all lowercase as nginx will convert them to all lowercase before trying to resolve.
Container setup examples
Create container via http validation
Let's assume our domain name is linuxserver-test.com and we would like our cert to also cover www.linuxserver-test.com and ombi.linuxserver-test.com. On the router, forward ports 80 and 443 to your host server. On your dns provider (if using your own domain), create an A record for the main domain and point it to your server IP (wan). Also create CNAMES for www and ombi and point them to the A record for the domain.
With docker cli, we'll first create a user defined bridge network if we haven't already docker network create lsio, and then create the container:
1
docker create \
2
  --name=swag \
3
  --cap-add=NET_ADMIN \
4
  --net=lsio \
5
  -e PUID=1000 \
6
  -e PGID=1000 \
7
  -e TZ=Europe/London \
8
  -e URL=linuxserver-test.com \
9
  -e SUBDOMAINS=www,ombi \
10
  -e VALIDATION=http \
11
  -p 443:443 \
12
  -p 80:80 \
13
  -v /home/aptalca/appdata/swag:/config \
14
  --restart unless-stopped \
15
  lscr.io/linuxserver/swag
Copied!
Once created, we do docker start swag to start it.
With docker compose, we can use the following yml:
1
---
2
version: "2.1"
3
services:
4
  swag:
5
    image: lscr.io/linuxserver/swag
6
    container_name: swag
7
    cap_add:
8
      - NET_ADMIN
9
    environment:
10
      - PUID=1000
11
      - PGID=1000
12
      - TZ=Europe/London
13
      - URL=linuxserver-test.com
14
      - SUBDOMAINS=www,ombi
15
      - VALIDATION=http
16
    volumes:
17
      - /home/aptalca/appdata/swag:/config
18
    ports:
19
      - 443:443
20
      - 80:80
21
    restart: unless-stopped
Copied!
We can fire up the container with docker-compose up -d
After the container is started, we'll watch the logs with docker logs swag -f. After some initial initialization, we will see the validation steps. After all the steps, it should print Server ready in the logs.
Now we can browse to https://www.linuxserver-test.com and we'll see the default landing page displayed.
Create container via dns validation with a wildcard cert
Let's assume our domain name is linuxserver-test.com and we would like our cert to also cover www.linuxserver-test.com, ombi.linuxserver-test.com and any other subdomain possible. On the router, we'll forward port 443 to our host server (Port 80 forwarding is optional).
We'll need to make sure that we are using a dns provider that is supported by this image. Currently the following dns plugins are supported: cloudflare, cloudxns, digitalocean, dnsimple, dnsmadeeasy, google, luadns, nsone, ovh, rfc2136 and route53. Your dns provider by default is the provider of your domain name and if they are not supported, it is very easy to switch to a different dns provider. Cloudflare is recommended due to being free and reliable. To switch to Cloudflare, you can register for a free account and follow their steps to point the nameservers to Cloudflare. The rest of the instructions assume that we are using the cloudflare dns plugin.
On our dns provider, we'll create an A record for the main domain and point it to our server IP (wan). We'll also create a CNAME for * and point it to the A record for the domain. On Cloudflare, we'll click on the orange cloud to turn it grey so that it is dns only and not cached/proxied by Cloudflare, which would add more complexities.
Now, let's get the container set up.
With docker cli, we'll first create a user defined bridge network if we haven't already docker network create lsio, and then create the container:
1
docker create \
2
  --name=swag \
3
  --cap-add=NET_ADMIN \
4
  --net=lsio \
5
  -e PUID=1000 \
6
  -e PGID=1000 \
7
  -e TZ=Europe/London \
8
  -e URL=linuxserver-test.com \
9
  -e SUBDOMAINS=wildcard \
10
  -e VALIDATION=dns \
11
  -e DNSPLUGIN=cloudflare \
12
  -p 443:443 \
13
  -p 80:80 \
14
  -v /home/aptalca/appdata/swag:/config \
15
  --restart unless-stopped \
16
  lscr.io/linuxserver/swag
Copied!
And we start the container via docker start swag
With docker compose, we'll use:
1
---
2
version: "2.1"
3
services:
4
  swag:
5
    image: lscr.io/linuxserver/swag
6
    container_name: swag
7
    cap_add:
8
      - NET_ADMIN
9
    environment:
10
      - PUID=1000
11
      - PGID=1000
12
      - TZ=Europe/London
13
      - URL=linuxserver-test.com
14
      - SUBDOMAINS=wildcard
15
      - VALIDATION=dns
16
      - DNSPLUGIN=cloudflare
17
    volumes:
18
      - /home/aptalca/appdata/swag:/config
19
    ports:
20
      - 443:443
21
      - 80:80
22
    restart: unless-stopped
Copied!
Then we'll fire up the container via docker-compose up -d
After the container is started, we'll watch the logs with docker logs swag -f. After some init steps, we'll notice that the container will give an error during validation due to wrong credentials. That's because we didn't enter the correct credentials for the Cloudflare api yet. We can browse to the location /config/dns-conf which is mapped from the host location (according to above settings) /home/aptalca/appdata/swag/dns-conf/ and edit the correct ini file for our dns provider. For Cloudflare, we'll enter our e-mail address and the api key. The api key can be retrieved by going to the Overview page and clicking on Get your API key link. We'll need the Global API Key.
Once we enter the credentials into the ini file, we'll restart the docker container via docker restart swag and again watch the logs. After successful validation, we should see the notice Server ready and our webserver should be up and accessible at https://www.linuxserver-test.com.
Create container via duckdns validation with a wildcard cert
We will first need to get a subdomain from DuckDNS. Let's assume we get linuxserver-test so our url will be linuxserver-test.duckdns.org. Then we'll need to make sure that the subdomain points to our server IP (wan) on the DuckDNS website. We can always use our DuckDNS docker image to keep the IP up to date. Don't forget to get the token for your account from DuckDNS. On the router, we'll forward port 443 to our host server (Port 80 forward is optional).
Now, let's get the container set up.
With docker cli, we'll first create a user defined bridge network if we haven't already docker network create lsio, and then create the container:
1
docker create \
2
  --name=swag \
3
  --cap-add=NET_ADMIN \
4
  --net=lsio \
5
  -e PUID=1000 \
6
  -e PGID=1000 \
7
  -e TZ=Europe/London \
8
  -e URL=linuxserver-test.duckdns.org \
9
  -e SUBDOMAINS=wildcard \
10
  -e VALIDATION=duckdns \
11
  -e DUCKDNSTOKEN=97654867496t0877648659765854 \
12
  -p 443:443 \
13
  -p 80:80 \
14
  -v /home/aptalca/appdata/swag:/config \
15
  --restart unless-stopped \
16
  lscr.io/linuxserver/swag
Copied!
And we start the container via docker start swag
With docker compose, we'll use:
1
---
2
version: "2.1"
3
services:
4
  swag:
5
    image: lscr.io/linuxserver/swag
6
    container_name: swag
7
    cap_add:
8
      - NET_ADMIN
9
    environment:
10
      - PUID=1000
11
      - PGID=1000
12
      - TZ=Europe/London
13
      - URL=linuxserver-test.duckdns.org
14
      - SUBDOMAINS=wildcard
15
      - VALIDATION=duckdns
16
      - DUCKDNSTOKEN=97654867496t0877648659765854
17
    volumes:
18
      - /home/aptalca/appdata/swag:/config
19
    ports:
20
      - 443:443
21
      - 80:80
22
    restart: unless-stopped
Copied!
Then we'll fire up the container via docker-compose up -d
After the container is started, we'll watch the logs with docker logs swag -f. We'll see some initialization and then we will see the validation steps. After all the steps, it should print Server ready in the logs.
Now we can access the webserver by browsing to https://www.linuxserver-test.duckdns.org.
NOTICE: Due to a DuckDNS limitation, our cert only covers the wildcard subdomains, but it doesn't cover the main url. So if we try to access https://linuxserver-test.duckdns.org, we'll see a browser warning about an invalid ssl cert. But accessing it through the www (or ombi or any other) subdomain should work fine.
Web hosting examples
Simple html web page hosting
Once we have a working container, we can drop our web documents in and modify the nginx config files to set up our webserver.
All the necessary files are under /config which is mapped from the host location (set by above examples) /home/aptalca/appdata/swag.
We can drop all of our web/html files into /config/www.
The main site config nginx uses can be found at /config/nginx/site-confs/default. Don't delete this file, as it will be regenerated on container restart, but feel free to modify as needed. By default, it is listening on port 443, and the root folder is set to /config/www, so if you drop a page1.html into that location, it will be accessible at https://linuxserver-test.com/page1.html.
To enable listening on port 80 and automatically redirecting to port 443 for enforcing ssl, uncomment the lines at the top of the default site config so it reads:
1
# redirect all traffic to https
2
server {
3
    listen 80;
4
    listen [::]:80;
5
    server_name _;
6
    return 301 https://$host$request_uri;
7
}
Copied!
After any changes to the config files, simply restart the container via docker restart swag to reload the nginx config.
Hosting a Wordpress site
Wordpress requires a mysql database. For that, we'll use the linuxserver MariaDB docker image.
Here's a docker compose stack to get both containers set up. For this exercise, we'll utilize the cloudflare dns plugin for Let's Encrypt validation, but you can use any other method to set it up as described in this linked section:
1
---
2
version: "2.1"
3
services:
4
  mariadb:
5
    image: lscr.io/linuxserver/mariadb
6
    container_name: mariadb
7
    environment:
8
      - PUID=1000
9
      - PGID=1000
10
      - MYSQL_ROOT_PASSWORD=mariadbpassword
11
      - TZ=Europe/London
12
      - MYSQL_DATABASE=WP_database
13
      - MYSQL_USER=WP_dbuser
14
      - MYSQL_PASSWORD=WP_dbpassword
15
    volumes:
16
      - /home/aptalca/appdata/mariadb:/config
17
    restart: unless-stopped
18
  swag:
19
    image: lscr.io/linuxserver/swag
20
    container_name: swag
21
    cap_add:
22
      - NET_ADMIN
23
    environment:
24
      - PUID=1000
25
      - PGID=1000
26
      - TZ=Europe/London
27
      - URL=linuxserver-test.com
28
      - SUBDOMAINS=wildcard
29
      - VALIDATION=dns
30
      - DNSPLUGIN=cloudflare
31
    volumes:
32
      - /home/aptalca/appdata/swag:/config
33
    ports:
34
      - 443:443
35
      - 80:80
36
    depends_on:
37
      - mariadb
38
    restart: unless-stopped
Copied!
And here are the docker cli versions (make sure you already created the lsio network as described above: Mariadb:
1
docker create \
2
  --name=mariadb \
3
  --net=lsio \
4
  -e PUID=1000 \
5
  -e PGID=1000 \
6
  -e MYSQL_ROOT_PASSWORD=mariadbpassword \
7
  -e TZ=Europe/London \
8
  -e MYSQL_DATABASE=WP_database \
9
  -e MYSQL_USER=WP_dbuser \
10
  -e MYSQL_PASSWORD=WP_dbpassword \
11
  -v /home/aptalca/appdata/mariadb:/config \
12
  --restart unless-stopped \
13
  lscr.io/linuxserver/mariadb
Copied!
SWAG:
1
docker create \
2
  --name=swag \
3
  --cap-add=NET_ADMIN \
4
  --net=lsio \
5
  -e PUID=1000 \
6
  -e PGID=1000 \
7
  -e TZ=Europe/London \
8
  -e URL=linuxserver-test.com \
9
  -e SUBDOMAINS=wildcard \
10
  -e VALIDATION=dns \
11
  -e DNSPLUGIN=cloudflare \
12
  -p 443:443 \
13
  -p 80:80 \
14
  -v /home/aptalca/appdata/swag:/config \
15
  --restart unless-stopped \
16
  lscr.io/linuxserver/swag
Copied!
Once the SWAG container is set up with ssl certs and the webserver is up, we'll download the latest Wordpress and untar it into our www folder:
1
wget https://wordpress.org/latest.tar.gz
2
tar xvf latest.tar.gz -C /home/aptalca/appdata/swag/www/
3
rm latest.tar.gz
Copied!
Now that we have all the wordpress files under the container's /config/www/wordpress folder, we'll change the root directive in our SWAG default site conf to point there. We'll find the line in /config/nginx/site-confs/default that reads root /config/www; and change it to root /config/www/wordpress; and restart SWAG.
Now we should be able to access our wordpress config page at https://linuxserver-test.com/wp-admin/install.php. We'll go ahead and enter mariadb as the Database Host address (we are using the container name as the dns hostname since both containers are in the same user defined bridge network), and also enter the Database Name, user and password we used in the mariadb config above (WP_database, WP_dbuser and WP_dbpassword).
Once we go through the rest of the install steps, our wordpress instance should be fully set up and available at https://linuxserver-test.com.
If you would like to have http requests on port 80 enabled and auto redirected to https on port 443, uncomment the relevant lines at the top of the default site config to read:
1
# redirect all traffic to https
2
server {
3
    listen 80;
4
    listen [::]:80;
5
    server_name _;
6
    return 301 https://$host$request_uri;
7
}
Copied!
Reverse Proxy
A reverse proxy is a type of proxy server that retrieves resources on behalf of a client from one or more servers. These resources are then returned to the client as if they originated from the Web server itself (Shamelessly borrowed from another post on our blog).
reverseproxy
In this case, a user or a client browser can connect to our SWAG container via https on port 443, request a service such as Ombi, then our SWAG container connects to the ombi container, retrieves the data and passes it on to the client via https with our trusted cert. The connection to ombi is local and does not need to be encrypted, but all communication between our SWAG container and the client browser will be encrypted.
Preset proxy confs
Our SWAG image comes with a list of preset reverse proxy confs for popular apps and services. They are hosted on Github and are pulled into the /config/nginx/proxy-confs folder as inactive sample files. To activate, one must rename a conf file to remove .sample from the filename and restart the SWAG container. Any proxy conf file in that folder with a name that matches *.subdomain.conf or *.subfolder.conf will be loaded in nginx during container start.
Most proxy confs work without any modification, but some may require other changes. All the required changes are listed at the top of each proxy conf. The conf files use container names to reach other containers and therefore the proxied containers should be named the same as listed in our documentation for each container.
The conf files also require that the SWAG container is in the same user defined bridge network as the other container so they can reach each other via container name as dns hostnames. Make sure you follow the instructions listed above in the Docker networking section.
Understanding the proxy conf structure
Subdomain proxy conf
Here's the preset proxy conf for Heimdall as a subdomain (ie. https://heimdall.linuxserver-test.com):
1
# make sure that your dns has a cname set for heimdall
2
​
3
server {
4
    listen 443 ssl;
5
    listen [::]:443 ssl;
6
​
7
    server_name heimdall.*;
8
​
9
    include /config/nginx/ssl.conf;
10
​
11
    client_max_body_size 0;
12
​
13
    # enable for ldap auth, fill in ldap details in ldap.conf
14
    #include /config/nginx/ldap.conf;
15
​
16
    # enable for Authelia
17
    #include /config/nginx/authelia-server.conf;
18
​
19
    location / {
20
        # enable the next two lines for http auth
21
        #auth_basic "Restricted";
22
        #auth_basic_user_file /config/nginx/.htpasswd;
23
​
24
        # enable the next two lines for ldap auth
25
        #auth_request /auth;
26
        #error_page 401 =200 /ldaplogin;
27
​
28
        # enable for Authelia
29
        #include /config/nginx/authelia-location.conf;
30
​
31
        include /config/nginx/proxy.conf;
32
        resolver 127.0.0.11 valid=30s;
33
        set $upstream_app heimdall;
34
        set $upstream_port 443;
35
        set $upstream_proto https;
36
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
37
​
38
    }
39
}
Copied!
Let's dissect this conf to look at what each directive or block does.
1
server {
2
}
Copied!
This is our server block. Whenever nginx gets a request from a client, it determines which server block should be processed based on the destination server name, port and other relevant info, and the matching server block determines how nginx handles and responds to the request.
1
    listen 443 ssl;
2
    listen [::]:443 ssl;
Copied!
This means that only requests coming to port 443 will match this server block.
1
    server_name heimdall.*;
Copied!
Only destination addresses that match heimdall.* will match this server block.
1
    include /config/nginx/ssl.conf;
Copied!
This directive injects the contents of our ssl.conf file here, which contains all ssl related settings (cert location, ciphers used, etc.).
1
    client_max_body_size 0;
Copied!
Removes the size limitation on uploads (default 1MB).
1
    # enable for ldap auth, fill in ldap details in ldap.conf
2
    #include /config/nginx/ldap.conf;
Copied!
Commented out (disabled) by default. When enabled, it will inject the contents of ldap.conf, necessary settings for LDAP auth.
1
    # enable for Authelia
2
    #include /config/nginx/authelia-server.conf;
Copied!
Commented out (disabled) by default. When enabled, it will inject the contents of authelia-server.conf, necessary settings for Authelia integration.
1
    location / {
2
    }
Copied!
Location blocks are used for subfolders or paths. After a server block is matched, nginx will look at the subfolder or path requested to match one of the location blocks inside the selected server block. This particular block in our example is for / so it will match any subfolder or path at this address.
1
        # enable the next two lines for http auth
2
        #auth_basic "Restricted";
3
        #auth_basic_user_file /config/nginx/.htpasswd;
Copied!
Commented out (disabled) by default. When enabled, it will use .htpasswd to perform user/pass authentication before allowing access.
1
        # enable the next two lines for ldap auth
2
        #auth_request /auth;
3
        #error_page 401 =200 /login;
Copied!
Commented out (disabled) by default. When enabled, it will use LDAP authentication before allowing access.
1
        # enable for Authelia
2
        #include /config/nginx/authelia-location.conf;
Copied!
Commented out (disabled) by default. When enabled, it will use Authelia authentication before allowing access.
1
        include /config/nginx/proxy.conf;
Copied!
Injects the contents of proxy.conf, which contains various directives and headers that are common for proxied connections.
1
        resolver 127.0.0.11 valid=30s;
Copied!
Tells nginx to use the docker dns to resolve the IP address when the container name is used as address in the next line.
1
        set $upstream_app heimdall;
2
        set $upstream_port 443;
3
        set $upstream_proto https;
4
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
Copied!
This is a bit of a tricky part. Normally, we could just put in the directive proxy_pass https://heimdall:443; and expect nginx to connect to Heimdall via its container name used as a dns hostname. Although it works for the most part, nginx has an annoying habit. During start, nginx checks all dns hostnames used in proxy_pass statements and if any one of them is not accessible, it refuses to start. We really don't want a stopped proxied container to prevent our webserver from starting up, so we use a trick.
If the proxy_pass statement contains a variable instead of a dns hostname, nginx doesn't check whether it's accessible or not during start. So here we are setting 3 variables, one named upstream_app with the value of heimdall, one named $upstream_port, with the value of the internal heimdall port 443, and one named $upstream_proto with the value set to https. We we use these variables as the address in the proxy_pass directive. That way, if the heimdall container is down for any reason, nginx can still start. When using a variable instead of hostname, we also have to set the resolver to docker dns in the previous line.
If the proxied container is not in the same user defined bridge network as SWAG (could be on a remote host, could be using host networking or macvlan), we can change the value of $upstream_app to an IP address instead: set $upstream_app 192.168.1.10;
Subfolder proxy conf
Here's the preset proxy conf for mytinytodo via a subfolder
1
# works with https://github.com/breakall/mytinytodo-docker
2
# set the mtt_url to 'https://your.domain.com/todo/' in db/config.php
3
​
4
location /todo {
5
    return 301 $scheme://$host/todo/;
6
}
7
location ^~ /todo/ {
8
​
9
    # enable the next two lines for http auth
10
    #auth_basic "Restricted";
11
    #auth_basic_user_file /config/nginx/.htpasswd;
12
​
13
    # enable the next two lines for ldap auth, also customize and enable ldap.conf in the default conf
14
    #auth_request /auth;
15
    #error_page 401 =200 /ldaplogin;
16
​
17
    # enable for Authelia, also enable authelia-server.conf in the default site config
18
    #include /config/nginx/authelia-location.conf;
19
​
20
    include /config/nginx/proxy.conf;
21
    resolver 127.0.0.11 valid=30s;
22
    set $upstream_app mytinytodo;
23
    set $upstream_port 80;
24
    set $upstream_proto http;
25
    proxy_pass $upstream_proto://$upstream_app:$upstream_port/;
26
}
Copied!
Unlike the subdomain proxy confs, here we do not have a server block. That is because all of the subfolder proxy confs get injected into the main server block of our root domain defined in the default site conf. So here we are only defining the location block for our specific subfolders.
Many of the elements are the same as the subdomain ones, so for those you can refer to the previous section. Let's take a look at some of the differences.
1
# works with https://github.com/breakall/mytinytodo-docker
2
# set the mtt_url to 'https://your.domain.com/todo/' in db/config.php
Copied!
These are the instructions to get the tinytodo container ready to work with our reverse proxy.
1
location ^~ /todo {
2
    return 301 $scheme://$host/todo/;
3
}
Copied!
Redirects requests for https://linuxserver-test.com/todo to https://linuxserver-test.com/todo/ (added forward slash at the end).
1
location ^~ /todo/ {
2
}
Copied!
Any requests sent to nginx where the destination starts with https://linuxserver-test.com/todo/ will match this location block.
1
    set $upstream_app mytinytodo;
2
    set $upstream_port 80;
3
    set $upstream_proto http;
4
    proxy_pass $upstream_proto://$upstream_app:$upstream_port/;
Copied!
Same as the previous example, we set a variable $upstream_app with the value mytinytodo and tell nginx to use the variable as the address. Keep in mind that the port listed here is the container port because nginx is connecting to this container directly via the docker network. So if our mytinytodo container has a port mapping of -p 8080:80, we still set $upstream_port variable to 80.
Nginx has an interesting behavior displayed here. Even though we define http://$upstream_mytinytodo:80/ as the address nginx should proxy, nginx actually connects to http://$upstream_mytinytodo:80/todo. Whenever we use a variable as part of the proxy_pass url, nginx automatically appends the defined location (in this case /todo) to the end of the proxy_pass url before it connects. If we include the subfolder, nginx will try to connect to http://$upstream_mytinytodo:80/todo/todo and will fail.
Ombi subdomain reverse proxy example
In this example, we will reverse proxy Ombi at the address https://ombi.linuxserver-test.com.
First let's make sure that we have a CNAME for ombi set up on our dns provider (a wildcard CNAME * will also cover this) and it is pointing to our A record that points to our server IP. If we are using the docker cli method, we also need to create the user defined bridge network (here named lsio) as described above. We also need to make sure that port 443 on our router is forwarded to the correct port on our server.
Here's a docker compose stack we can use to set up both containers:
1
---
2
version: "2.1"
3
services:
4
  ombi:
5
    image: lscr.io/linuxserver/ombi
6
    container_name: ombi
7
    environment:
8
      - PUID=1000
9
      - PGID=1000
10
      - TZ=Europe/London
11
    volumes:
12
      - /home/aptalca/appdata/ombi:/config
13
    ports:
14
      - 3579:3579
15
    restart: unless-stopped
16
  swag:
17
    image: lscr.io/linuxserver/swag
18
    container_name: swag
19
    cap_add:
20
      - NET_ADMIN
21
    environment:
22
      - PUID=1000
23
      - PGID=1000
24
      - TZ=Europe/London
25
      - URL=linuxserver-test.com
26
      - SUBDOMAINS=wildcard
27
      - VALIDATION=dns
28
      - DNSPLUGIN=cloudflare
29
    volumes:
30
      - /home/aptalca/appdata/swag:/config
31
    ports:
32
      - 443:443
33
      - 80:80
34
    restart: unless-stopped
Copied!
And here are the docker cli versions: Ombi:
1
docker create \
2
  --name=ombi \
3
  --net=lsio \
4
  -e PUID=1000 \
5
  -e PGID=1000 \
6
  -e TZ=Europe/London \
7
  -p 3579:3579 \
8
  -v /home/aptalca/appdata/ombi:/config \
9
  --restart unless-stopped \
10
  lscr.io/linuxserver/ombi
Copied!
SWAG:
1
docker create \
2
  --name=swag \
3
  --cap-add=NET_ADMIN \
4
  --net=lsio \
5
  -e PUID=1000 \
6
  -e PGID=1000 \
7
  -e TZ=Europe/London \
8
  -e URL=linuxserver-test.com \
9
  -e SUBDOMAINS=wildcard \
10
  -e VALIDATION=dns \
11
  -e DNSPLUGIN=cloudflare \
12
  -p 443:443 \
13
  -p 80:80 \
14
  -v /home/aptalca/appdata/swag:/config \
15
  --restart unless-stopped \
16
  lscr.io/linuxserver/swag
Copied!
Once our containers up and running (and we confirm we can reach the placeholder page at https://linuxserver-test.com), we simply rename the file ombi.subdomain.conf.sample under /config/nginx/proxy-confs/ to ombi.subdomain.conf and we restart the SWAG container. Now when we browser to https://ombi.linuxserver-test.com we should see the Ombi gui.
Nextcloud subdomain reverse proxy example
Nextcloud is a bit trickier because the app has various security measures built-in, forcing us to configure certain options manually.
As with the other examples, let's make sure that we have a CNAME for nextcloud set up on our dns provider (a wildcard CNAME * will also cover this) and it is pointing to our A record that points to our server IP. If we are using the docker cli method, we also need to create the user defined bridge network (here named lsio) as described above. For DuckDNS, we do not need to create CNAMES, as all sub-subdomains automatically point to the same IP as our custom subdomain, but we need to make sure that it is the correct IP address for our server. We also need to make sure that port 443 on our router is forwarded to the correct port on our server.
In this example we'll use the duckdns wildcard cert, but you can use any Let's Encrypt validation you like as described above​
Here's a docker compose stack to set up our SWAG, nextcloud and mariadb containers:
1
---
2
version: "2.1"
3
services:
4
  nextcloud:
5
    image: lscr.io/linuxserver/nextcloud
6
    container_name: nextcloud
7
    environment:
8
      - PUID=1000
9
      - PGID=1000
10
      - TZ=Europe/London
11
    volumes:
12
      - /home/aptalca/appdata/nextcloud/config:/config
13
      - /home/aptalca/appdata/nextcloud/data:/data
14
    depends_on:
15
      - mariadb
16
    restart: unless-stopped
17
  mariadb:
18
    image: lscr.io/linuxserver/mariadb
19
    container_name: mariadb
20
    environment:
21
      - PUID=1000
22
      - PGID=1000
23
      - MYSQL_ROOT_PASSWORD=mariadbpassword
24
      - TZ=Europe/London
25
      - MYSQL_DATABASE=nextcloud
26
      - MYSQL_USER=ncuser
27
      - MYSQL_PASSWORD=ncpassword
28
    volumes:
29
      - /home/aptalca/appdata/mariadb:/config
30
    restart: unless-stopped
31
  swag:
32
    image: lscr.io/linuxserver/swag
33
    container_name: swag
34
    cap_add:
35
      - NET_ADMIN
36
    environment:
37
      - PUID=1000
38
      - PGID=1000
39
      - TZ=Europe/London
40
      - URL=linuxserver-test.duckdns.org
41
      - SUBDOMAINS=wildcard
42
      - VALIDATION=duckdns
43
      - DUCKDNSTOKEN=97654867496t0877648659765854
44
    volumes:
45
      - /home/aptalca/appdata/swag:/config
46
    ports:
47
      - 443:443
48
      - 80:80
49
    restart: unless-stopped
Copied!
And here are the docker cli versions: Nextcloud:
1
docker create \
2
  --name=nextcloud \
3
  --net=lsio
4
  -e PUID=1000 \
5
  -e PGID=1000 \
6
  -e TZ=Europe/London \
7
  -v /home/aptalca/appdata/nextcloud/config:/config \
8
  -v /home/aptalca/appdata/nextcloud/data:/data \
9
  --restart unless-stopped \
10
  lscr.io/linuxserver/nextcloud
Copied!
Mariadb:
1
docker create \
2
  --name=mariadb \
3
  --net=lsio \
4
  -e PUID=1000 \
5
  -e PGID=1000 \
6
  -e MYSQL_ROOT_PASSWORD=mariadbpassword \
7
  -e TZ=Europe/London \
8
  -e MYSQL_DATABASE=nextcloud \
9
  -e MYSQL_USER=ncuser \
10
  -e MYSQL_PASSWORD=ncpassword \
11
  -v /home/aptalca/appdata/mariadb:/config \
12
  --restart unless-stopped \
13
  lscr.io/linuxserver/mariadb
Copied!
SWAG:
1
docker create \
2
  --name=swag \
3
  --cap-add=NET_ADMIN \
4
  --net=lsio \
5
  -e PUID=1000 \
6
  -e PGID=1000 \
7
  -e TZ=Europe/London \
8
  -e URL=linuxserver-test.duckdns.org \
9
  -e SUBDOMAINS=wildcard \
10
  -e VALIDATION=duckdns \
11
  -e DUCKDNSTOKEN=97654867496t0877648659765854 \
12
  -p 443:443 \
13
  -p 80:80 \
14
  -v /home/aptalca/appdata/swag:/config \
15
  --restart unless-stopped \
16
  lscr.io/linuxserver/swag
Copied!
Now we find the file named nextcloud.subdomain.conf.sample under SWAG's /config/nginx/proxy-confs folder and rename it to nextcloud.subdomain.conf, then restart the SWAG container.
If this is the first time we are accessing Nextcloud (we've never accessed it locally before), we can simply navigate to https://nextcloud.linuxserver-test.duckdns.org and we should see the Nextcloud set up page. We'll fill out the info, use the mariadb user ncuser and the password we selected in the environment variable (ncpassword in the above example) and we'll use mariadb as the Database Host address (container name as dns hostname).
Screenshot-2019-04-14-at-18.35.02---Edited
We should then be able to go through the intro slides and then see the Nextcloud dashboard with our shiny padlock icon next to the address bar.
Screenshot-2019-04-14-at-18.40.45---Edited
If this is an existing Nextcloud instance, or we set it up locally via the host IP address and local port, Nextcloud will reject proxied connections. In that case, we have to follow the instructions at the top of the nextcloud.subdomain.conf file:
1
# assuming this container is called "swag", edit your nextcloud container's config
2
# located at /config/www/nextcloud/config/config.php and add the following lines before the ");":
3
#  'trusted_proxies' => ['swag'],
4
#  'overwrite.cli.url' => 'https://nextcloud.your-domain.com/',
5
#  'overwritehost' => 'nextcloud.your-domain.com',
6
#  'overwriteprotocol' => 'https',
7
#
8
# Also don't forget to add your domain name to the trusted domains array. It should look somewhat like this:
9
#  array (
10
#    0 => '192.168.0.1:444', # This line may look different on your setup, don't modify it.
11
#    1 => 'nextcloud.your-domain.com',
12
#  ),
Copied!
These settings will tell Nextcloud to respond to queries where the destination address is our domain name.
If you followed the above directions to set it up for the first time, you only need to add the line 'trusted_proxies' => ['swag'],, otherwise nextcloud 16+ shows a warning about incorrect reverse proxy settings. By default, HSTS is disabled in SWAG config, because it is a bit of a sledgehammer that prevents loading of any http assets on the entire domain. You can enable it in SWAG's ssl.conf.
Plex subfolder reverse proxy example
In this example, we will set up Plex as a subfolder so it will be accessible at https://linuxserver-test.com/plex. We will initially set up Plex with host networking through its local IP and will connect to it from the same subnet. If we are on a different subnet, or if using a bridge network, we can use the PLEX_CLAIM variable to automatically claim the server with our plex account.
Once the Plex server is set up, it is safe to switch it to bridge networking from host.
Here's a docker compose stack we can use to set up both containers:
1
---
2
version: "2.1"
3
services:
4
  plex:
5
    image: lscr.io/linuxserver/plex
6
    container_name: plex
7
    network_mode: host
8
    environment:
9
      - PUID=1000
10
      - PGID=1000
11
      - VERSION=docker
12
    volumes:
13
      - /home/aptalca/appdata/plex:/config
14
      - /home/aptalca/tvshows:/data/tvshows
15
      - /home/aptalca/movies:/data/movies
16
    restart: unless-stopped
17
  swag:
18
    image: lscr.io/linuxserver/swag
19
    container_name: swag
20
    cap_add:
21
      - NET_ADMIN
22
    environment:
23
      - PUID=1000
24
      - PGID=1000
25
      - TZ=Europe/London
26
      - URL=linuxserver-test.com
27
      - SUBDOMAINS=wildcard
28
      - VALIDATION=dns
29
      - DNSPLUGIN=cloudflare
30
    volumes:
31
      - /home/aptalca/appdata/swag:/config
32
    ports:
33
      - 443: