Add a page for Qt Debian packages instructions

Added a new page that provides instructions on
how to use Qt Debian packages.

Change-Id: Ie486a058e82bae5d974a4ffb2858c5dc6d6e5b45
Reviewed-by: Iikka Eklund <iikka.eklund@qt.io>
(cherry picked from commit 0e2f40447ea1bc5cf12f836520f6e6d1467ad7cc)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 160 insertions, 0 deletions

diff --git a/doc/src/platforms/debian-packages.qdoc b/doc/src/platforms/debian-packages.qdoc
new file mode 100644
index 00000000..8b79acea
--- /dev/null
+++ b/doc/src/platforms/debian-packages.qdoc
@@ -0,0 +1,160 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page qt-debian-packages.html
+    \brief Instructions How to Use Enterprise Qt Debian Packages
+    \title Enterprise Qt Debian Packages
+
+    To use Debian packaging with Qt, add your enterprise repositories to Advanced
+    Packaging Tool (APT). For details, see
+    \l{Debian Repository Configuration Format}.
+
+    To use the enterprise repositories, you need to:
+    \list
+        \li \l{Installing Public GPG Key}{Install a public GPG key} for enterprise repositories
+        \li \l{Configuring Authentication}
+        {Configure Qt Account based authentication} for enterprise repository
+        access
+        \li \l{Repository Configuration Example}{Configure repositories}
+    \endlist
+
+    \section1 Debian Repository Configuration Format
+
+    To add extra repositories for APT, insert repositories into a file with an
+    extension of \e{.list} under the \e{/etc/apt/sources.list.d} directory. For
+    each repository, add a new entry in the file. The generic format is as
+    follows:
+
+    \badcode
+    deb [arch=<arch> signed-by=<path>] <REPO_URL> <DIST> <COMPONENT(s)>
+    \endcode
+
+    An example of an enterprise repository entry:
+
+    \badcode
+    $ sudo nano /etc/apt/sources.list.d/tqtc.list
+
+        deb [arch=arm64 signed-by=/home/<user>/keyrings/tqtc/qt-company-debian-repo.gpg] https://debian-packages.qt.io/debian/enterprise/qt-6.3.1-arm64 tqtc-focal main
+    \endcode
+
+    See \l{Repository information for Qt Releases} for detailed information
+    on how you can configure repositories per Qt release and architecture.
+
+    \section1 Installing Public GPG Key
+
+    Install a public GPG (GNU Privacy Guard) key for Qt Enterprise Debian
+    repositories as follows:
+
+    \badcode
+    $ mkdir -p $HOME/keyrings/tqtc  # pick a suitable location for you!
+    $ wget https://cdn.qt.io/debian/keys/qt-company-debian-repo.gpg $HOME/keyrings/tqtc
+    \endcode
+
+    \section1 Configuring Authentication
+
+    To access the listed repositories, you need an enterprise Qt Account
+    or an evaluation Qt Account.
+
+    \note If your password contains special characters, you may need to escape
+    those by using \b'\\' or \b'%40'.
+
+    Configure the Qt Account credentials for your APT package manager as follows:
+
+    \badcode
+    $ sudo nano /etc/apt/auth.conf
+
+          machine https://debian-packages.qt.io
+          login <Qt Account login name (email)>
+          password <Qt Account password>
+    \endcode
+
+    \section1 Repository Configuration Example
+
+    The following code snippet demonstrates how you can configure repositories
+    for multiple Qt repositories:
+
+    \badcode
+    $ sudo nano /etc/apt/sources.list.d/tqtc.list
+
+        deb [arch=arm64 signed-by=/home/<user>/keyrings/tqtc/qt-company-debian-repo.gpg] https://debian-packages.qt.io/debian/enterprise/qt-6.3.1-arm64 tqtc-focal main
+        deb [arch=amd64 signed-by=/home/<user>/keyrings/tqtc/qt-company-debian-repo.gpg] https://debian-packages.qt.io/debian/enterprise/qt-6.3.1-amd64 tqtc-focal main
+
+        # in case you need to put your Qt Account credentials directly into the repository entry
+        deb [arch=arm64 signed-by=/home/<user>/keyrings/tqtc/qt-company-debian-repo.gpg] https://john.smith@company:password123@debian-packages.qt.io/debian/enterprise/qt-6.4.0-arm64 tqtc-jammy main
+    \endcode
+
+    See \l{Repository information for Qt Releases} to pick the needed
+    repositories into your \e{/etc/apt/sources.list.d/tqtc.list} file.
+
+    \section1 Troubleshooting
+
+    \section2 Difficulties in authentication
+
+    The server may response with the following HTTP error codes:
+
+    \section3 401 Unauthorized
+
+    Wrong credentials. User email and password must be provided in correct format.
+
+    Also, try storing the credentials directly into the repository config:
+
+    \badcode
+    deb [...] https://<Qt Account email>:<Qt Account passwd>@https://debian-packages.qt.io/..... 
+    \endcode
+
+    If your password contains special characters, you may need to escape those
+    for APT. Use '\' or '%40' for escaping those characters or try changing your
+    Qt Account password.
+
+    \section3 403 Forbidden
+
+    Missing credentials.
+
+    \section3 429 Too Many Requests
+
+    User has sent too much \b{failed} requests (3 requests per minute).
+
+    \section3 500 Internal Server Error
+
+    Contact \l{https://www.qt.io/contact-us}{Qt support}.
+
+    \section2 Difficulties with repository GPG key usage
+
+    An alternative to 'signed-by' usage attribute in the repository config is to
+    install the key in the following way, althoug this is not recommended as
+    it's deprecated way to install it:
+
+    \badcode
+    $ sudo apt-key add qt-company-debian-repo.gpg
+    \endcode
+
+    \section1 Repository information for Qt Releases
+
+    Below you can find the Qt releases that the enterprise Qt Debian packaging
+    supports. Pick the needed repositories and add them to your
+    \e{/etc/apt/sources.list.d/tqtc.list} as instructed above.
+
+    Also, the following tables list the installation directories on your
+    system and the Linux distribution used to build the packages.
+
+    \section2 Qt 6.3.1
+
+    \table
+    \header
+        \li Architecture
+        \li Distribution (build platform)
+        \li Installation directory
+        \li Package resource list entries for APT
+    \row
+        \li arm64
+        \li focal-fossa (Ubuntu 20.04)
+        \li /opt/qt-6.3.1/aarch64-linux-gnu/
+        \li deb [arch=amd64 signed-by=<path>] https://debian-packages.qt.io/debian/enterprise/qt-6.3.1-amd64 tqtc-focal main
+    \row
+        \li amd64
+        \li focal-fossa (Ubuntu 20.04)
+        \li /opt/qt-6.3.1/x86_64-linux-gnu/
+        \li deb [arch=arm64 signed-by=<path>] https://debian-packages.qt.io/debian/enterprise/qt-6.3.1-arm64 tqtc-focal main
+    \endtable
+*/