diff --git a/docs/u_e-nginx.md b/docs/u_e-nginx.md index 9581dd9b6..b82081aea 100644 --- a/docs/u_e-nginx.md +++ b/docs/u_e-nginx.md @@ -1,11 +1,19 @@ +## SSL + +Please see [Advanced SSL](https://mailcow.github.io/mailcow-dockerized-docs/firststeps-ssl/) and explicitly check `ADDITIONAL_SERVER_NAMES` for SSL configuration. + +Please do not add ADDITIONAL_SERVER_NAMES when you plan to use a different web root. + +## New site + To create persistent (over updates) sites hosted by mailcow: dockerized, a new site configuration must be placed inside `data/conf/nginx/`: +A good template to begin with: + ``` nano data/conf/nginx/my_custom_site.conf ``` -A good template to begin with: - ``` hl_lines="16" server { ssl_certificate /etc/ssl/mail/cert.pem; @@ -19,15 +27,20 @@ server { ssl_session_tickets off; index index.php index.html; client_max_body_size 0; + # Location: data/web root /web; + # Location: data/web/mysite.com + #root /web/mysite.com include /etc/nginx/conf.d/listen_plain.active; include /etc/nginx/conf.d/listen_ssl.active; server_name mysite.example.org; server_tokens off; + # This allows acme to be validated even with a different web root location ^~ /.well-known/acme-challenge/ { - allow all; default_type "text/plain"; + rewrite /.well-known/acme-challenge/(.*) /$1 break; + root /web/.well-known/acme-challenge/; } if ($scheme = http) { @@ -36,8 +49,14 @@ server { } ``` +## New site with proxy to a remote location + Another example with a reverse proxy configuration: +``` +nano data/conf/nginx/my_custom_site.conf +``` + ``` hl_lines="16 28" server { ssl_certificate /etc/ssl/mail/cert.pem; @@ -77,8 +96,9 @@ server { } ``` +## Config expansion in mailcows Nginx -The filename is not important, as long as the filename carries a .conf extension. +The filename used for a new site is not important, as long as the filename carries a .conf extension. It is also possible to extend the configuration of the default file `site.conf` file: @@ -86,7 +106,7 @@ It is also possible to extend the configuration of the default file `site.conf` nano data/conf/nginx/site.my_content.custom ``` -This filename does not need to have a ".conf" extension, but follows the pattern `site.*.custom`, where `*` is a custom name. +This filename does not need to have a ".conf" extension but follows the pattern `site.*.custom`, where `*` is a custom name. If PHP is to be included in a custom site, please use the PHP-FPM listener on phpfpm:9002 or create a new listener in `data/conf/phpfpm/php-fpm.d/pools.conf`. @@ -96,3 +116,4 @@ Restart Nginx (and PHP-FPM, if a new listener was created): docker-compose restart nginx-mailcow docker-compose restart php-fpm-mailcow ``` +