Update pg_tde docker topic with proper parameters based on user feedback (#802)

* updated docker

updated with up to date information for pg_tde encryption parameters, also, cleaned the document a bit, added a paragraph recommending the user to see the pg_tde docs, added a note bolding the fact that we do not recommend using a local keyring file and we suggest using an external KMS.

* small fix

fixed name of step 5 and a small link fix

* Update docker.md

updated parameters with correct ones and also removed $ signs so users can actually copy paste the commands properly in cli

Author: Andriciuc

docs/docker.md

@@ -4,7 +4,7 @@ Docker images of Percona Distribution for PostgreSQL are hosted publicly on [Doc
 
 For more information about using Docker, see the [Docker Docs :octicons-link-external-16:](https://docs.docker.com/).
 
-!!! note ""
+!!! note
 
     Make sure that you are using [the latest version of Docker :octicons-link-external-16:](https://docs.docker.com/get-docker/). The ones provided via `apt` and `yum` may be outdated and cause errors.
 
@@ -34,94 +34,90 @@ For more information about using Docker, see the [Docker Docs :octicons-link-ext
 1. Start a Percona Distribution for PostgreSQL container as follows:
 
     ```{.bash data-prompt="$"}
-    $ docker run --name container-name -e POSTGRES_PASSWORD=secret -d percona/percona-distribution-postgresql:{{dockertag}}
-    ```    
+    docker run --name container-name -e POSTGRES_PASSWORD=secret -d percona/percona-distribution-postgresql:{{dockertag}}
+    ```
 
-    Where:    
+    Where:
 
     * `container-name` is the name you assign to your container
     * `POSTGRES_PASSWORD` is the superuser password 
-    * `{{dockertag}}` is the tag specifying the version you need. Docker identifies the architecture (x86_64 or ARM64) and pulls the respective image. See the [full list of tags :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/).     
-    
+    * `{{dockertag}}` is the tag specifying the version you need. Docker identifies the architecture (x86_64 or ARM64) and pulls the respective image. See the [full list of tags :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/).
 
-    !!! tip     
+    !!! tip
 
         You can secure the password by exporting it to the environment file and using that to start the container.    
 
         1. Export the password to the environment file:    
 
             ```{.bash data-prompt="$"}
-            $ echo "POSTGRES_PASSWORD=secret" > .my-pg.env
+            echo "POSTGRES_PASSWORD=secret" > .my-pg.env
             ```     
 
         2. Start the container:       
 
             ```{.bash data-prompt="$"}
-            $ docker run --name container-name --env-file ./.my-pg.env -d percona/percona-distribution-postgresql:{{dockertag}}
+            docker run --name container-name --env-file ./.my-pg.env -d percona/percona-distribution-postgresql:{{dockertag}}
             ```
 
-2. Connect to the container's interactive terminal: 
+2. Connect to the container's interactive terminal:
 
     ```{.bash data-prompt="$"}
-    $ docker exec -it container-name bash
+    docker exec -it container-name bash
     ```
 
     The `container-name` is the name of the container that you started in the previous step.
 
-
 ## Connect to Percona Distribution for PostgreSQL from an application in another Docker container
 
 This image exposes the standard PostgreSQL port (`5432`), so container linking makes the instance available to other containers. Start other containers like this in order to link it to the Percona Distribution for PostgreSQL container:
 
 ```{.bash data-prompt="$"}
-$ docker run --name app-container-name --network container:container-name -d app-that-uses-postgresql 
+docker run --name app-container-name --network container:container-name -d app-that-uses-postgresql 
 ```
 
 where:
 
-* `app-container-name` is the name of the container where your application is running, 
-* `container name` is the name of your Percona Distribution for PostgreSQL container, and 
+* `app-container-name` is the name of the container where your application is running,
+* `container name` is the name of your Percona Distribution for PostgreSQL container, and
 * `app-that-uses-postgresql` is the name of your PostgreSQL client.
 
 ## Connect to Percona Distribution for PostgreSQL from the `psql` command line client
 
 The following command starts another container instance and runs the `psql` command line client against your original container, allowing you to execute SQL statements against your database:
 
 ```{.bash data-prompt="$"}
-$ docker run -it --network container:db-container-name --name container-name percona/percona-distribution-postgresql:{{dockertag}} psql -h address -U postgres
+docker run -it --network container:db-container-name --name container-name percona/percona-distribution-postgresql:{{dockertag}} psql -h address -U postgres
 ```
 
 Where:
 
 * `db-container-name` is the name of your database container
 * `container-name` is the name of your container that you will use to connect to the database container using the `psql` command line client
-* `{{dockertag}}` is the tag specifying the version you need. Docker identifies the architecture (x86_64 or ARM64) and pulls the respective image. 
-* `address` is the network address where your database container is running. Use 127.0.0.1, if the database container is running on the local machine/host.   
+* `{{dockertag}}` is the tag specifying the version you need. Docker identifies the architecture (x86_64 or ARM64) and pulls the respective image.
+* `address` is the network address where your database container is running. Use 127.0.0.1, if the database container is running on the local machine/host.
 
 ## Enable encryption
 
-Percona Distribution for PostgreSQL Docker image includes the `pg_tde` extension to provide data encryption. You must explicitly enable it when you start the container. 
+Percona Distribution for PostgreSQL Docker image includes the `pg_tde` extension to provide data encryption. You must explicitly enable it when you start the container. For more information, see the [pg_tde documentation](https://docs.percona.com/pg-tde/index.html).
 
-Here's how to do this:
-{.power-number}
+Follow these steps to enable `pg_tde`:
 
 1. Start the container with the `ENABLE_PG_TDE=1` environment variable:
 
     ```{.bash data-prompt="$"}
-    $ docker run --name container-name -e ENABLE_PG_TDE=1 -e POSTGRES_PASSWORD=sUpers3cRet  -d percona/percona-distribution-postgresql:{{dockertag}}
+    docker run --name container-name -e ENABLE_PG_TDE=1 -e POSTGRES_PASSWORD=sUpers3cRet  -d percona/percona-distribution-postgresql:{{dockertag}}
     ```
 
     where:
-    
+
     * `container-name` is the name you assign to your container
     * `ENABLE_PG_TDE=1` adds the `pg_tde` to the `shared_preload_libraries` and enables the custom storage manager
-    * `POSTGRES_PASSWORD` is the superuser password 
-
+    * `POSTGRES_PASSWORD` is the superuser password
 
 2. Connect to the container and start the interactive `psql` session:
 
     ```{.bash data-prompt="$"}
-    $ docker exec -it container-name psql
+    docker exec -it container-name psql
     ```
 
     ??? example "Sample output"
@@ -139,23 +135,24 @@ Here's how to do this:
     CREATE EXTENSION pg_tde;
     ```
 
-4. Configure a key provider. In this sample configuration intended for testing and development purpose, we use a local keyring provider. 
+4. Configure a key provider with a keyring file. This setup is intended for development and stores the keys unencrypted in the specified data file. The below sample configuration is intended for testing and development purposes.
 
-    For production use, set up an external key management store and configure an external key provider. Refer to the [Setup :octicons-link-external-16:](https://docs.percona.com/pg-tde/setup.html#key-provider-configuration) chapter in the `pg_tde` documentation.
+    !!! note
+         For production use, we **strongly recommend** setting up an external key management store and configure an external key provider. Refer to the [Setup :octicons-link-external-16:](https://docs.percona.com/pg-tde/setup.html#key-provider-configuration) topic in the `pg_tde` documentation.
 
     <i warning>:material-information: Warning:</i> This example is for testing purposes only:
 
 	```sql
-	SELECT pg_tde_add_key_provider_file('file-keyring','/tmp/pg_tde_test_local_keyring.per');
+	SELECT pg_tde_add_database_key_provider_file('file-vault', '/tmp/pg_tde_test_001_basic.per');
     ```
 
-5. Add a principal key
+5. Set the principal key:
 
     ```sql
-    SELECT pg_tde_set_principal_key('test-db-master-key','file-keyring');
+    SELECT pg_tde_set_key_using_database_key_provider('test-db-key', 'file-vault');
     ```
 
-    The key is autogenerated. You are ready to use data encryption.
+    The key is auto-generated. You are ready to use data encryption.
 
 6. Create a table with encryption enabled. Pass the `USING tde_heap` clause to the `CREATE TABLE` command:
 
@@ -167,7 +164,7 @@ Here's how to do this:
 
 To enable the `pg_stat_monitor` extension after launching the container, do the following:
 
-* connect to the server, 
+* connect to the server,
 * select the desired database and enable the `pg_stat_monitor` view for that database:
 
    ```sql
@@ -180,7 +177,7 @@ To enable the `pg_stat_monitor` extension after launching the container, do the
    \d pg_stat_monitor;
    ```
 
-??? example "Output"   
+??? example "Output"
 
     ```
                              View "public.pg_stat_monitor"
@@ -228,6 +225,5 @@ To enable the `pg_stat_monitor` extension after launching the container, do the
     wait_event_type     | text                     |           |          |
     ```
 
-Note that the `pg_stat_monitor` view is available only for the databases where you enabled it. If you create a new database, make sure to create the view for it to see its statistics data.
-
-
+!!! note
+     The `pg_stat_monitor` view is available only for the databases where you enabled it. If you create a new database, make sure to create the view for it to see its statistics data.