docs: added 502 page instructions for nginx and apache

docs/admin/apache-conf-example.rst

@@ -1,99 +1,103 b''
 .. _apache-conf-eg:
 
 Apache Configuration Example
 ----------------------------
 
 Use the following example to configure Apache as a your web server.
 Below config if for an Apache Reverse Proxy configuration.
 
 .. note::
 
    Apache requires the following modules to be enabled. Below is an example
    how to enable them on Ubuntu Server
 
 
 .. code-block:: bash
 
     $ sudo a2enmod proxy
     $ sudo a2enmod proxy_http
     $ sudo a2enmod proxy_balancer
     $ sudo a2enmod headers
     $ sudo a2enmod ssl
     $ sudo a2enmod rewrite
 
     # requires Apache 2.4+, required to handle websockets/channelstream
     $ sudo a2enmod proxy_wstunnel
 
 
 .. code-block:: apache
 
     ## HTTP to HTTPS rewrite
     <VirtualHost *:80>
        ServerName rhodecode.myserver.com
        DocumentRoot /var/www/html
        Redirect permanent / https://rhodecode.myserver.com/
     </VirtualHost>
 
     ## MAIN SSL enabled server
     <VirtualHost *:443>
 
         ServerName rhodecode.myserver.com
         ServerAlias rhodecode.myserver.com
 
         ## Skip ProxyPass the _static to backend server
         #ProxyPass /_static !
 
         ## serve static files by Apache, recommended for performance
         #Alias /_static/rhodecode /home/ubuntu/.rccontrol/community-1/static
 
         ## Allow Apache to access the static files in this directory
         #<Directory /home/ubuntu/.rccontrol/community-1/static/>
         #    AllowOverride none
         #    Require all granted
         #</Directory>
 
         RequestHeader set X-Forwarded-Proto "https"
 
         ## channelstream websocket handling
         ProxyPass /_channelstream ws://localhost:9800
         ProxyPassReverse /_channelstream ws://localhost:9800
 
         <Proxy *>
           Order allow,deny
           Allow from all
         </Proxy>
 
         # Directive to properly generate url (clone url) for RhodeCode
         ProxyPreserveHost On
 
         # Url to running RhodeCode instance. This is shown as `- URL:` when
         # running rccontrol status.
         ProxyPass / http://127.0.0.1:10002/ timeout=7200 Keepalive=On
         ProxyPassReverse / http://127.0.0.1:10002/
 
         # Increase headers for large Mercurial headers
         LimitRequestLine 16380
 
         # strict http prevents from https -> http downgrade
         Header always set Strict-Transport-Security "max-age=63072000; includeSubdomains; preload"
 
         # Set x-frame options
         Header always append X-Frame-Options SAMEORIGIN
 
         # To enable https use line below
         # SetEnvIf X-Url-Scheme https HTTPS=1
 
         # SSL setup
         SSLEngine On
         SSLCertificateFile /etc/apache2/ssl/rhodecode.myserver.pem
         SSLCertificateKeyFile /etc/apache2/ssl/rhodecode.myserver.key
 
         SSLProtocol             all -SSLv2 -SSLv3
         SSLCipherSuite          ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA
         SSLHonorCipherOrder     on
 
         # Diffie-Hellman parameter for DHE ciphersuites, recommended 2048 bits
         #SSLOpenSSLConfCmd DHParameters "/etc/apache2/dhparam.pem"
 
+        ## custom 502 error page. Will be displayed while RhodeCode server
+        ## is turned off
+        ErrorDocument 502 /path/to/.rccontrol/enterprise-1/static/502.html
+
     </VirtualHost>
 

docs/admin/nginx-config-example.rst

@@ -1,135 +1,136 b''
 Nginx Configuration Example
 ---------------------------
 
 Use the following example to configure Nginx as a your web server.
 
 
 .. code-block:: nginx
 
     ## rate limiter for certain pages to prevent brute force attacks
     limit_req_zone  $binary_remote_addr  zone=dl_limit:10m   rate=1r/s;
 
     ## custom log format
     log_format log_custom '$remote_addr - $remote_user [$time_local] '
                           '"$request" $status $body_bytes_sent '
                           '"$http_referer" "$http_user_agent" '
                           '$request_time $upstream_response_time $pipe';
 
     ## define upstream (local RhodeCode instance) to connect to
     upstream rc {
         # Url to running RhodeCode instance.
         # This is shown as `- URL:` in output from rccontrol status.
         server 127.0.0.1:10002;
 
         # add more instances for load balancing
         # server 127.0.0.1:10003;
         # server 127.0.0.1:10004;
     }
 
     ## HTTP to HTTPS rewrite
     server {
         listen          80;
         server_name     rhodecode.myserver.com;
 
         if ($http_host = rhodecode.myserver.com) {
             rewrite  (.*)  https://rhodecode.myserver.com$1 permanent;
         }
     }
 
     ## Optional gist alias server, for serving nicer GIST urls.
     server {
         listen          443;
         server_name     gist.myserver.com;
         access_log      /var/log/nginx/gist.access.log log_custom;
         error_log       /var/log/nginx/gist.error.log;
 
         ssl on;
         ssl_certificate     gist.rhodecode.myserver.com.crt;
         ssl_certificate_key gist.rhodecode.myserver.com.key;
 
         ssl_session_timeout 5m;
 
         ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
         ssl_prefer_server_ciphers on;
         ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
 
         # strict http prevents from https -> http downgrade
         add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";
 
         # Diffie-Hellman parameter for DHE ciphersuites, recommended 2048 bits
         #ssl_dhparam /etc/nginx/ssl/dhparam.pem;
 
         rewrite ^/(.+)$ https://rhodecode.myserver.com/_admin/gists/$1;
         rewrite (.*)    https://rhodecode.myserver.com/_admin/gists;
     }
 
 
     ## MAIN SSL enabled server
     server {
         listen       443 ssl;
         server_name  rhodecode.myserver.com;
 
         access_log   /var/log/nginx/rhodecode.access.log log_custom;
         error_log    /var/log/nginx/rhodecode.error.log;
 
         ssl on;
         ssl_certificate     rhodecode.myserver.com.crt;
         ssl_certificate_key rhodecode.myserver.com.key;
 
         ssl_session_timeout 5m;
 
         ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
         ssl_prefer_server_ciphers on;
         ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
 
         # Diffie-Hellman parameter for DHE ciphersuites, recommended 2048 bits
         #ssl_dhparam /etc/nginx/ssl/dhparam.pem;
 
         include     /etc/nginx/proxy.conf;
 
         ## serve static files by Nginx, recommended for performance
         # location /_static/rhodecode {
         #    alias /path/to/.rccontrol/enterprise-1/static;
         # }
 
         ## channelstream websocket handling
         location /_channelstream {
             rewrite /_channelstream/(.*) /$1 break;
 
             proxy_pass                  http://127.0.0.1:9800;
 
             proxy_connect_timeout        10;
             proxy_send_timeout           10m;
             proxy_read_timeout           10m;
             tcp_nodelay                  off;
             proxy_set_header             Host $host;
             proxy_set_header             X-Real-IP $remote_addr;
             proxy_set_header             X-Url-Scheme $scheme;
             proxy_set_header             X-Forwarded-Proto $scheme;
             proxy_set_header             X-Forwarded-For $proxy_add_x_forwarded_for;
             gzip                         off;
             proxy_http_version           1.1;
             proxy_set_header Upgrade     $http_upgrade;
             proxy_set_header Connection  "upgrade";
         }
 
         location /_admin/login {
             ## rate limit this endpoint
             limit_req  zone=dl_limit  burst=10  nodelay;
             try_files $uri @rhode;
         }
 
         location / {
             try_files $uri @rhode;
         }
 
         location @rhode {
             proxy_pass      http://rc;
         }
 
-        ## custom 502 error page
+        ## custom 502 error page. Will be displayed while RhodeCode server
+        ## is turned off
         error_page 502 /502.html;
         location = /502.html {
            root  /path/to/.rccontrol/enterprise-1/static;
         }
     }
  No newline at end of file