Addded docs about pg_service QField configuration and QFieldCloud secrets

documentation/how-to/pg-service.md

@@ -0,0 +1,25 @@
+---
+title: PostgreSQL service
+---
+
+# PostgreSQL service
+
+A `pg_service.conf` file allows to use an named alias for a PostgreSQL server connection. Instead of storing hostname, port, database name and more into the QGIS Project file, these can be stored separately. It is even possible to store username and password in a `pg_service.conf` file, to avoid having this stored in clear text in the QGIS Project.
+
+Read more about PostgreSQL services in the [QGIS documentation](https://docs.qgis.org/3.22/en/docs/user_manual/managing_data_source/opening_data.html#postgresql-service-connection-file).
+
+# QField - Direct Connection
+
+If you directly connect from QGIS to your database you can make use of a `pg_service.conf` file by placing it in the QField data folder. You can place your file either on the Internal Device Storage or on the SD Card Storage. You can check the path for the QField data folder in the bottom of the `About QField` screen in the app.
+
+Usually the path on Android devices looks something like this: `/Android/data/ch.opengis.qfield/files/QField`.
+
+!!! note
+    Unlike on *NIX systems where the file is named `.pg_service.conf`, the file on Android is named `pg_service.conf` without a leading dot sign (`.`).
+
+# QFieldCloud
+
+QFieldCloud support `pg_service.conf` configurations too. You need to configure your PostgreSQL layers with "Offline editing" cloud action and store your service settings on QFieldCloud Project's Secrets page.
+
+Read more [how to configure PostgreSQL service](../reference/qfieldcloud/secrets.md) in the QFieldCloud documentation.
+

documentation/reference/qfieldcloud/permissions.md

@@ -57,6 +57,7 @@ QFieldCloud provides a fine grained access control over projects with the concep
 | Update user's informations                                                    | ❌ | ❌ | ✅ | ‒  | ‒  | ‒  | ‒  | ‒  | ❌ | ❌ | ❌ |   |
 | Delete user                                                                   | ❌ | ❌ | ✅ | ‒  | ‒  | ‒  | ‒  | ‒  | ❌ | ❌ | ❌ |   |
 | Get API status                                                                | ✅ | ✅ | ‒  | ‒  | ‒  | ‒  | ‒  | ‒  | ‒  | ‒  | ‒  |   |
+| Add and remove secrets                                                        | ‒  | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ‒  | ‒  | ‒  |   |
 
 ## Roles
 

documentation/reference/qfieldcloud/secrets.md

@@ -0,0 +1,64 @@
+---
+title: Secrets
+---
+
+# Secrets
+
+Secrets are settings that are securely stored in an encrypted way. Project's jobs will automatically have access to their secrets. There are two types of secrets in QFieldCloud:
+
+- **environment variables** - Environment variables will be available to QGIS while your project jobs are running.
+- **pg_service configurations** - Adding a PostgreSQL/PostGIS connection as defined in the `pg_service.conf` configuration file.
+
+!!! note
+    Once added, a secret can only be removed, but cannot be edited.
+
+!!! warning
+    QFieldCloud makes sure your credentials are stored in a secured and encrypted manner. Nevertheless, we advice our users to use roles with the least privileges in shared environments to prevent potential leakage.
+    Also note all users with upload file permissions can potentially access the values of those credentials too.
+
+
+## Adding a new secret
+
+Adding a new secret on QFieldCloud is an easy process of only three steps.
+
+1. Navigating to the project' secrets page.
+2. Pressing **Add a new secret** button and choosing the type of secret you want to add.
+3. Storing the secret contents.
+
+!![Project secret page after pressing the **Add a new secret** button.](../../assets/images/secrets.png)
+
+
+## Environment variable
+
+Environment variables will be available to QGIS while your project jobs are running.
+
+You need to fill in the environment variable name (capitals only) and the environment variable value as free text.
+
+!![Adding an environment variable.](../../assets/images/secrets-envvar.png)
+
+
+## pg_service configuration
+
+Adding a PostgreSQL/PostGIS connection as defined in `pg_service.conf` configuration file. The "Advanced editor" allows to paste the `pg_service.conf` file contents directly. If you use multiple service definitions, you should add multiple secrets for each of them.
+
+!!! note
+    QFieldCloud secrets are available only during project's job runs, which allows you to configure your PostgreSQL layers as "Offline editing". You **cannot** use QFieldCloud secrets to distribute `pg_service.conf` files across devices. For security reasons, you have to do this manually. You can read [how to configuring QField to use a `pg_service.conf`](../../how-to/pg-service.md) file.
+
+To add a PostgreSQL service you can use either the simple visual editor, or directly edit the service configuration as plain text.
+
+- service name
+- database name
+- database user
+- database password
+- database host
+- database port
+- database SSL connection
+
+For other service settings you can use the **Add extra pgservice field** button to add pairs of settings and their values. Alternatively, you can edit the service configuration directly as plain text.
+
+!![Adding a PostgreSQL service - Simple editor.](../../assets/images/secrets-pgservice-simple.png)
+
+The advanced configuration allows you to directly edit the settings as plain text. This is convenient in cases you want to copy and paste your settings directly from a `pg_service.conf` file.
+
+!![Adding a PostgreSQL service - Advanced editor.](../../assets/images/secrets-pgservice-advanced.png)
+

mkdocs.yml

@@ -82,6 +82,7 @@ nav:
       - how-to/live-default-value.md
       - how-to/outside-layers.md
       - how-to/movable-project.md
+      - how-to/pg-service.md
   - Technical reference:
       - reference/index.md
       - reference/data-format.md
@@ -90,6 +91,7 @@ nav:
           - reference/qfieldcloud/projects.md
           - reference/qfieldcloud/permissions.md
           - reference/qfieldcloud/jobs.md
+          - reference/qfieldcloud/secrets.md
           - reference/qfieldcloud/specs.md
           - reference/qfieldcloud/api.md
           - reference/qfieldcloud/system.md