Documentation on how to run the appstore behind a reverse proxy

Change-Id: I260d87ac94d69be69437392b0c53912383cd00d6
Fixes: AUTOSUITE-501
Reviewed-by: Kavindra Palaraja <kpalaraja@luxoft.com>

1 files changed, 128 insertions, 0 deletions

diff --git a/doc/src/deployment-server-http-server-setup.qdoc b/doc/src/deployment-server-http-server-setup.qdoc
new file mode 100644
index 0000000..677ab80
--- /dev/null
+++ b/doc/src/deployment-server-http-server-setup.qdoc
@@ -0,0 +1,128 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 Luxoft Sweden AB
+** Copyright (C) 2018 Pelagicore AG
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Auto Deployment Server.
+**
+** $QT_BEGIN_LICENSE:FDL-QTAS$
+** Commercial License Usage
+** Licensees holding valid commercial Qt Automotive Suite licenses may use
+** this file in accordance with the commercial license agreement provided
+** with the Software or, alternatively, in accordance with the terms
+** contained in a written agreement between you and The Qt Company.  For
+** licensing terms and conditions see https://www.qt.io/terms-conditions.
+** For further information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtauto-deployment-server-http-server-setup.html
+    \previouspage Qt Automotive Suite Deployment Server
+    \contentspage Qt Automotive Suite
+
+
+    \title Set up a Production server with Apache, Lighttpd or Nginx
+
+The Deployment Server can be set up in combination with a regular web server: Apache, Lighttpd, or
+ Nginx. This web server can be used to reduce the number of open ports or to add a layer of SSL
+ encryption.
+
+In the Django version that is used for the deployment server, there are two possible setups for
+ running with another web server:
+\list
+  \li reverse proxy setup - which we describe here
+  \li WSGI setup - for brevity, this setup is left out of scope, as it is similar in functionality
+      to reverse proxy setup
+\endlist
+
+\section1 Reverse Proxy Setup
+
+For all web servers, the preliminary setup is the same. First, the deployment server should be set
+ up in the same way as for standalone use. If the server will be used in a subdirectory of the
+ web server (like http://hostname.domain/url_prefix/ ), then this prefix should be set up in
+ \e{appstore/settings.py}, in a \c{URL_PREFIX} variable.
+
+In this example, this variable is set to 'url_prefix'; note the lack of slashes. Also, if
+ \c{URL_PREFIX} is set to a non-empty value, \c{STATIC_URL} should be changed too, to start from
+ set prefix. So \c{STATIC_URL} would be \c{'/<url_prefix>/static/'} instead of \c{'/static/'}
+
+After that, the server should be set up to run as a service, on any free port.
+This is done by running:
+\code
+  ./venv/bin/python manage.py runserver 127.0.0.1:<port>
+\endcode
+Assuming that the Python virtual environment was set up in the project directory, under the
+ \e{venv} subdirectory.
+
+On Linix and Unix systems, to run as a non-root user, you must use a port number larger than 1024.
+
+Once the service is running, set up the web server's configuration.
+
+\section2 Apache2 Setup
+
+First, enable \b{mod_proxy} and \b{mod_proxy_http} modules in Apache, by running
+\c{a2enmod proxy proxy_http}.
+
+Then insert this code snippet into the VirtualHost section of your configuration file:
+
+\code
+    <Location '/<url_prefix>/'>
+            ProxyPass "http://127.0.0.1:<port>/<url_prefix>/"
+            ProxyPassReverse "http://127.0.0.1:<port>/<url_prefix>/"
+    </Location>
+\endcode
+
+If necessary, add configuration section to set up access permissions to this URL.
+
+After setting this up, reload web server's configuration.
+
+\section2 Lighttpd Setup
+
+For Lighttpd, first, enable mod_proxy, by running \c{lighttpd-enable-mod proxy} as root.
+Alternatively, add the following line in your \e{/etc/lighttpd/lighttpd.conf} file:
+\code
+server.modules   += ( "mod_proxy" )
+\endcode
+
+Next, add the following code snippet:
+\code
+$HTTP["url"] =~ "^/<url_prefix>/" {
+      proxy.balance = "hash"
+      proxy.server  = ( "" => ( ( "host" => "127.0.0.1", "port" => "<port>" ),
+                              ) )
+}
+
+\endcode
+
+Where \e{<url_prefix>} is the same as in \e{settings.py} file, and \e{<port>} is the port on which the
+deployment server instance is running.
+
+Finally, reload the Lighttpd server's configuration.
+
+\section2 Nginx Setup
+
+For Nginx, setup consists of adding a code snippet into server configuration, inside of a
+\c{server { } } statement and restarting the server.
+
+The code that needs to be added is:
+\code
+    location /<url_prefix>/ {
+        proxy_pass http://127.0.0.1:<port>/<url_prefix>/;
+    }
+\endcode
+
+Where \e{<url_prefix>} is the same as in \e{settings.py} file, and \e{<port>} is the port on which the
+deployment server instance is running.
+
+*/