mirror
/
docker-documentation
kopia lustrzana https://github.com/linuxserver/docker-documentation
1
0
Forkuj 0
Kod Zgłoszenia Packages Projekty Wydania Wiki Aktywność

Merge pull request #29 from linuxserver/zerossl 

add zerossl info to swag doc
pull/30/head
aptalca 2021-01-13 11:41:02 -05:00 zatwierdzone przez GitHub
rodzic eea493808e c2fb847dee
commit dcbcbafe7c
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: 4AEE18F83AFDEB23
1 zmienionych plików z 55 dodań i 42 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

97
general/swag.md
Wyświetl plik

@ -4,11 +4,12 @@ The goal of this guide is to give you ideas on what can be accomplished with the
* [Introduction](#introduction) * [Introduction](#introduction)
* [What are SSL certs?](#what-are-ssl-certs) * [What are SSL certs?](#what-are-ssl-certs)
* [What is Let's Encrypt?](#what-is-lets-encrypt) * [What is Let's Encrypt (and/or ZeroSSL)?](#what-is-lets-encrypt-andor-zerossl)
* [Creating a SWAG container](#creating-a-swag-container) * [Creating a SWAG container](#creating-a-swag-container)
* [Docker cli](#docker-cli) * [Docker cli](#docker-cli)
* [Docker compose](#docker-compose) * [Docker compose](#docker-compose)
* [Authorization method](#authorization-method) * [Authorization method](#authorization-method)
* [Cert provider (Let's Encrypt vs ZeroSSL)](#cert-provider-lets-encrypt-vs-zerossl)
* [Port forwards](#port-forwards) * [Port forwards](#port-forwards)
* [Docker networking](#docker-networking) * [Docker networking](#docker-networking)
* [Container setup examples](#container-setup-examples) * [Container setup examples](#container-setup-examples)
@ -36,9 +37,9 @@ The goal of this guide is to give you ideas on what can be accomplished with the
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. 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? ## 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](https://letsencrypt.org/), one can get free certs via automated means. 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](https://letsencrypt.org/) and [ZeroSSL](https://zerossl.com/), one can get free certs via automated means.
The [SWAG docker image](https://hub.docker.com/r/linuxserver/swag), published and maintained by [LinuxServer.io](https://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](https://hub.docker.com/r/linuxserver/mariadb). The [SWAG docker image](https://hub.docker.com/r/linuxserver/swag), published and maintained by [LinuxServer.io](https://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](https://hub.docker.com/r/linuxserver/mariadb).
@ -58,6 +59,7 @@ docker create \
-e URL=yourdomain.url \ -e URL=yourdomain.url \
-e SUBDOMAINS=www, \ -e SUBDOMAINS=www, \
-e VALIDATION=http \ -e VALIDATION=http \
-e CERTPROVIDER= `#optional` \
-e DNSPLUGIN=cloudflare `#optional` \ -e DNSPLUGIN=cloudflare `#optional` \
-e DUCKDNSTOKEN=<token> `#optional` \ -e DUCKDNSTOKEN=<token> `#optional` \
-e EMAIL=<e-mail> `#optional` \ -e EMAIL=<e-mail> `#optional` \
@ -68,7 +70,7 @@ docker create \
-p 80:80 `#optional` \ -p 80:80 `#optional` \
-v </path/to/appdata/config>:/config \ -v </path/to/appdata/config>:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
## docker-compose ## docker-compose
@ -77,10 +79,10 @@ Compatible with docker-compose v2 schemas.
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -91,6 +93,7 @@ services:
- URL=yourdomain.url - URL=yourdomain.url
- SUBDOMAINS=www, - SUBDOMAINS=www,
- VALIDATION=http - VALIDATION=http
- CERTPROVIDER= #optional
- DNSPLUGIN=cloudflare #optional - DNSPLUGIN=cloudflare #optional
- DUCKDNSTOKEN=<token> #optional - DUCKDNSTOKEN=<token> #optional
- EMAIL=<e-mail> #optional - EMAIL=<e-mail> #optional
@ -126,6 +129,16 @@ The validation is performed when the container is started for the first time. Ng
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. 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](https://letsencrypt.org/) or [ZeroSSL](https://zerossl.com/). Both services use the [ACME protocol](https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment) 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 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. 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.
@ -167,7 +180,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
Once created, we do `docker start swag` to start it. Once created, we do `docker start swag` to start it.
@ -176,10 +189,10 @@ With docker compose, we can use the following yml:
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -232,7 +245,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
And we start the container via `docker start swag` And we start the container via `docker start swag`
@ -241,10 +254,10 @@ With docker compose, we'll use:
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -294,7 +307,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
And we start the container via `docker start swag` And we start the container via `docker start swag`
@ -303,10 +316,10 @@ With docker compose, we'll use:
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -368,10 +381,10 @@ Here's a docker compose stack to get both containers set up. For this exercise,
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
mariadb: mariadb:
image: linuxserver/mariadb image: ghcr.io/linuxserver/mariadb
container_name: mariadb container_name: mariadb
environment: environment:
- PUID=1000 - PUID=1000
@ -385,7 +398,7 @@ services:
- /home/aptalca/appdata/mariadb:/config - /home/aptalca/appdata/mariadb:/config
restart: unless-stopped restart: unless-stopped
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -423,7 +436,7 @@ docker create \
-e MYSQL_PASSWORD=WP_dbpassword \ -e MYSQL_PASSWORD=WP_dbpassword \
-v /home/aptalca/appdata/mariadb:/config \ -v /home/aptalca/appdata/mariadb:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/mariadb ghcr.io/linuxserver/mariadb
``` ```
SWAG: SWAG:
@ -444,7 +457,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
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: 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:
@ -721,10 +734,10 @@ Here's a docker compose stack we can use to set up both containers:
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
ombi: ombi:
image: linuxserver/ombi image: ghcr.io/linuxserver/ombi
container_name: ombi container_name: ombi
environment: environment:
- PUID=1000 - PUID=1000
@ -736,7 +749,7 @@ services:
- 3579:3579 - 3579:3579
restart: unless-stopped restart: unless-stopped
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -769,7 +782,7 @@ docker create \
-p 3579:3579 \ -p 3579:3579 \
-v /home/aptalca/appdata/ombi:/config \ -v /home/aptalca/appdata/ombi:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/ombi ghcr.io/linuxserver/ombi
``` ```
SWAG: SWAG:
@ -790,7 +803,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
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. 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.
@ -808,10 +821,10 @@ Here's a docker compose stack to set up our SWAG, nextcloud and mariadb containe
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
nextcloud: nextcloud:
image: linuxserver/nextcloud image: ghcr.io/linuxserver/nextcloud
container_name: nextcloud container_name: nextcloud
environment: environment:
- PUID=1000 - PUID=1000
@ -824,7 +837,7 @@ services:
- mariadb - mariadb
restart: unless-stopped restart: unless-stopped
mariadb: mariadb:
image: linuxserver/mariadb image: ghcr.io/linuxserver/mariadb
container_name: mariadb container_name: mariadb
environment: environment:
- PUID=1000 - PUID=1000
@ -838,7 +851,7 @@ services:
- /home/aptalca/appdata/mariadb:/config - /home/aptalca/appdata/mariadb:/config
restart: unless-stopped restart: unless-stopped
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -871,7 +884,7 @@ docker create \
-v /home/aptalca/appdata/nextcloud/config:/config \ -v /home/aptalca/appdata/nextcloud/config:/config \
-v /home/aptalca/appdata/nextcloud/data:/data \ -v /home/aptalca/appdata/nextcloud/data:/data \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/nextcloud ghcr.io/linuxserver/nextcloud
``` ```
Mariadb: Mariadb:
@ -889,7 +902,7 @@ docker create \
-e MYSQL_PASSWORD=ncpassword \ -e MYSQL_PASSWORD=ncpassword \
-v /home/aptalca/appdata/mariadb:/config \ -v /home/aptalca/appdata/mariadb:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/mariadb ghcr.io/linuxserver/mariadb
``` ```
SWAG: SWAG:
@ -910,7 +923,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
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. 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.
@ -955,10 +968,10 @@ Here's a docker compose stack we can use to set up both containers:
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
plex: plex:
image: linuxserver/plex image: ghcr.io/linuxserver/plex
container_name: plex container_name: plex
network_mode: host network_mode: host
environment: environment:
@ -971,7 +984,7 @@ services:
- /home/aptalca/movies:/data/movies - /home/aptalca/movies:/data/movies
restart: unless-stopped restart: unless-stopped
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -1005,7 +1018,7 @@ docker create \
-v /home/aptalca/tvshows:/data/tvshows \ -v /home/aptalca/tvshows:/data/tvshows \
-v /home/aptalca/movies:/data/movies \ -v /home/aptalca/movies:/data/movies \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/plex ghcr.io/linuxserver/plex
``` ```
SWAG: SWAG:
@ -1026,7 +1039,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
Once the containers are set up, we browse to `http://LOCALSERVERIP:32400/web` and set up our Plex server with our Plex account. Then we can find the file named `plex.subfolder.conf.sample` under our SWAG container's `/config/nginx/proxy-confs` folder and rename it to `plex.subfolder.conf`. Once the containers are set up, we browse to `http://LOCALSERVERIP:32400/web` and set up our Plex server with our Plex account. Then we can find the file named `plex.subfolder.conf.sample` under our SWAG container's `/config/nginx/proxy-confs` folder and rename it to `plex.subfolder.conf`.
@ -1047,10 +1060,10 @@ Here's a docker compose stack we can use to set up both containers:
```yaml ```yaml
--- ---
version: "2" version: "2.1"
services: services:
heimdall: heimdall:
image: linuxserver/heimdall image: ghcr.io/linuxserver/heimdall
container_name: heimdall container_name: heimdall
environment: environment:
- PUID=1000 - PUID=1000
@ -1060,7 +1073,7 @@ services:
- /home/aptalca/appdata/heimdall:/config - /home/aptalca/appdata/heimdall:/config
restart: unless-stopped restart: unless-stopped
swag: swag:
image: linuxserver/swag image: ghcr.io/linuxserver/swag
container_name: swag container_name: swag
cap_add: cap_add:
- NET_ADMIN - NET_ADMIN
@ -1092,7 +1105,7 @@ docker create \
-e TZ=Europe/London \ -e TZ=Europe/London \
-v /home/aptalca/appdata/heimdall:/config \ -v /home/aptalca/appdata/heimdall:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/heimdall ghcr.io/linuxserver/heimdall
``` ```
SWAG: SWAG:
@ -1113,7 +1126,7 @@ docker create \
-p 80:80 \ -p 80:80 \
-v /home/aptalca/appdata/swag:/config \ -v /home/aptalca/appdata/swag:/config \
--restart unless-stopped \ --restart unless-stopped \
linuxserver/swag ghcr.io/linuxserver/swag
``` ```
Once the containers are set up, we'll find the file named `heimdall.subfolder.conf.sample` under SWAG's `/config/nginx/proxy-confs` folder and rename it to `heimdall.subfolder.conf`. If we look inside that conf file, we'll see that it is set to use `location / {`, which will cause an issue because there is already a location defined for `/` inside the default site config for SWAG. So we need to edit the default site config at `/config/nginx/site-confs/default` and comment out the location block for `/` inside our main server block so it reads: Once the containers are set up, we'll find the file named `heimdall.subfolder.conf.sample` under SWAG's `/config/nginx/proxy-confs` folder and rename it to `heimdall.subfolder.conf`. If we look inside that conf file, we'll see that it is set to use `location / {`, which will cause an issue because there is already a location defined for `/` inside the default site config for SWAG. So we need to edit the default site config at `/config/nginx/site-confs/default` and comment out the location block for `/` inside our main server block so it reads: