add new docs and removed old examples

docs/satosa-nginx-vhost.md

@@ -0,0 +1,106 @@
+## Nginx Virtual Host example
+
+NGINX is quick and light web server.
+Nginx is commonly used as frontend proxy for Satosa and his implementation Satosa-saml2spid.
+On follow some configuration examples.
+
+### General information
+* In all example in this doc, the discovery page and errors pages are served directly from NGINX as static file. In some case you can use uWSGI to serve static files, but normally isn't a good choice 
+* For security reasons, all authentication connection, must be encrypted through HTTPS protocol
+* For security reasons, https protocol use exclusively TLS1.3 to encrypt
+* In all example we use `try_files` directive. With this directive you can test if the request is to a file or send there to a proxy location. In these examples:
+* 1. Test if the request is a existent directory with a `index.html` file. If the request is `/pippo` NGINX try to serve `/usr/share/nginx/html/pippo/index.html`
+* 2. Test if  exists a file with the request path. If request is `/pippo/pluto.html`, NGINX try to serve `/usr/share/nginx/html/pippo/pluto.html`
+* 3. Send the request to `@satosa` location 
+* `@satosa` location contain the proxy informations
+* NGINX can read the system environments. This is useful to configure NGINX in docker.
+### Docker host and uWSGI connection from network
+
+#### Details
+* The `server_name` is configured bu `$NGINX_HOST` environment. You change this with a static dns name
+* In docker compose, if you create more replicas of a service, the service name is a pointment to all istances
+* the certificates must be valid for the current host name
+* The root path is `/usr/share/nginx/html` for docker but you can use your preferred path
+* if you don't want personalize the errors pages you can remove the errors configurations
+* @satosa location use the uWSGI protocol for proxy
+
+#### satosa.conf
+```
+server {
+    listen 443 ssl;
+    server_name  $NGINX_HOST;
+    ssl_protocols TLSv1.3;
+    ssl_certificate /etc/nginx/certs/proxy_local.pem;
+    ssl_certificate_key /etc/nginx/certs/proxy_local.key;
+
+    # max upload size
+    client_max_body_size 10m;
+
+    # very long url for delega ticket
+    large_client_header_buffers 4 16k;
+
+    # deny iFrame
+    add_header X-Frame-Options "DENY";
+
+    add_header X-Content-Type-Options nosniff;
+    add_header X-XSS-Protection "1; mode=block";
+    add_header X-Robots-Tag none;
+
+    root /usr/share/nginx/html;
+    try_files $uri/index.html $uri @satosa;
+
+    location @satosa {
+      include /etc/nginx/uwsgi_params;
+      
+      uwsgi_pass satosa-saml2spid:10000;
+      uwsgi_param Host $host;
+      uwsgi_param X-Real-IP $remote_addr;
+      uwsgi_param X-Forwarded-For $proxy_add_x_forwarded_for;
+      uwsgi_param X-Forwarded-Proto $http_x_forwarded_proto;
+      uwsgi_param HTTP_X_FORWARDED_PROTOCOL https;
+
+      uwsgi_connect_timeout 75s;
+      uwsgi_read_timeout 40;
+      uwsgi_buffer_size          128k;
+      uwsgi_buffers              4 256k;
+      uwsgi_busy_buffers_size    256k;
+      uwsgi_param SERVER_ADDR $server_addr;
+    }
+
+    error_page 404 /404.html;
+    location = /404.html {
+        root   /usr/share/nginx/html/errors;
+    }
+
+    error_page 403 /403.html;
+    location = /403.html {
+        root   /usr/share/nginx/html/errors;
+    }
+
+    # redirect server error pages to the static page /50x.html
+    error_page 500 502 503 504  /50x.html;
+    location = /50x.html {
+        root   /usr/share/nginx/html/errors;
+    }
+}
+```
+
+#### proxy to socket
+If you want use a local socket uwsgy server you must change the `uwsgi_pass` key:
+```
+uwsgy_pass unix:///opt/satosa-saml2/tmp/sockets/satosa.sock;
+```
+where `unix://` is the url protocol and `/opt/satosa-saml2/tmp/sockets/satosa.socks` is the socket path
+
+#### nginx host log
+If you want save the NGINX log for this host you can add this directive in the virtual host:
+```
+  access_log /var/log/nginx/satosa.access.log;
+  error_log  /var/log/nginx/satosa.error.log error;
+```
+For docker instance the logs are sent to STDOUT and going in docker logs. This directive is normally not needed.
+
+### Insights
+* For more details on satosa-nginx compose service read [satosa-nginx_compose doc](./satosa-nginx_compose.md)
+* For more details on Satosa-saml2spid docker compose profiles read [docker-compose-profiles page](./docker-compose-profiles.md)
+* For more details on NGINX try_files directive read the [official docs](https://www.slingacademy.com/article/nginx-try_files-directive-explained-with-examples/)

docs/satosa-nginx_compose_service.md

@@ -1,14 +1,62 @@
 ## satosa-nginx Compose service
 
-This service run a container with the last version of [Docker official NGINX](https://hub.docker.com/_/nginx/) image. 
+This service run a container with the last version of [Docker official Alpine NGINX](https://hub.docker.com/_/nginx/) image. 
 This container work as [uWSGI](https://en.wikipedia.org/wiki/UWSGI) proxy to [satosa-saml2spid](./satosa-saml2spid_compose_service.md) containers and serve static file like the discovery page.
 
 ### Environments
+| Environment | from            | Default value | Description
+| ----------- | --------------- | ------------- | -----------
+| NGINX_HOST  | SATOSA_HOSTNAME | localhost     | Hostname in satosa virtualhost
+| TZ          | TZ              | Europe/Rome   | Set Time Zone for the istance
 
-### volumes
+### Volumes
+| from           | to                    | mode | Description
+| -------------- | --------------------- | ---- | ------------
+| ./nginx/conf.d | /etc/nginx/conf.d     | ro   | this directory contain all NGINX virtualst, read [Virtual Sost section](#vitual-host) 
+| ./nginx/certs  | /etx/nginx/certs      | ro   | This directory contain the https cerificates, read [Satosa Virtual Host section](#satosa-vitual-host)
+| ./nginx/html   | /usr/share/nginx/html | ro   | This directory contain the html static file for default virtual host, read [Static files section](#static-files)
 
-### virtual host
+*All `from path` are relative to Docker-compose directory*
 
-#### proxy
+### Virtual Hosts
+Default NGINX conf import the additional configurations from `/etc/nginx/conf.d/*.conf`. The Path `Docker-compose/nginx/conf.d` is mounted in `/etc/nginx/conf.d` of NGINX container. Each `*.conf` file present in theese directory is included in the NGINX congifuration.
+
+In `Docker-compose/nginx/conf.d` is preconfigured the file `default.conf` with [Satosa Virtual Host][#satosa-vitual-host]. You can add more `.conf` file and more virtual host, buth generally is not clever.
+
+#### Satosa Virtual host
+The Satosa Virtual Host listen exclusively on port 443 over protocol https.
+The HTTPS protocol il limited at TLS1.3.
+The older version of TLS and SSL are denyed
+
+NGINX configuration accept configurations from environments. In the default configuration the `server_name` is definied with with `$NGINX_HOST` env. If is not present this variable, Docker Compose assign `localhost` as `NGINX_HOST` value.
+
+TLS certificates will be searched in:
+* `ssl_certificate /etc/nginx/certs/proxy_local.pem` - public certificate
+* `ssl_certificate_key /etc/nginx/certs/proxy_local.key` - private key
+
+On default the directory `Docker-compose/nginx/certs` is mounted on `/etc/nginx/certs`.
+An self signed certificate for server name `localhost` is persent in the certs directory. To public the host you must overwrite these file with a valid certificate for you serrver name.
+
+The virtual host root is set on `/usr/share/nginx/html`, the `Docker-compose/nginx/html` path is mounted over this directory.
+To update the stati file you must edit the files in `Docker-compose/nginx/html` path.
+
+For security are added these header key
+* `X-Frame-Options "DENY"` to block the IFRAME
+* `X-Content-Type-Options nosniff` prevent mime type sniffing
+* `X-XSS-Protection "1; mode=block"` prevents some categories of XSS attacks
+* `X-Robots-Tag none` crawler are not welcome
+
+`location @satosa` contain all information to send and get data from satosa-saml2spid uWSGI server.
+The default configuration set `satosa-saml2spid:1000` as reverse uWSGI proxy destination.
+This permit to balance the connection with multiple satosa-saml2spid istance.
+
+Satosa Virtual Host use the `try_files` directive to send the request on the proxy.
+The proxy test if the request is sended to a existent file. If the file not exists send the request to @satosa location. On detail:
+1. Test if the request is a existent directory with a `index.html` file. Example: if the request is `/pippo` NGINX try to serve `/usr/share/nginx/html/pippo/index.html`
+2. Test if  exists a file with the request path. Example: if request is `/pippo/pluto.html`, NGINX try to serve `/usr/share/nginx/html/pippo/pluto.html`
+3. Send the request to `@satosa` location
+
+### Insights
+* For more details and example on NGINX satosa virtual host read [satosa-vitual-host doc](./satosa-virtual-host.md)
+* For more details on Satosa-saml2spid docker compose profiles read [docker-compose-profiles page](./docker-compose-profiles.md)
 
-c